Backstop is a great project, but it is intended to compare the same project across time (for example, you are working on a site, take a snapshot of the site, then make changes, then compare the changes). This makes things a bit difficult to understand in a training session where you only have an hour to learn something that requires a whole process to have. Plus, if you are using your local machine as your testing machine, you have to make sure you have a local URL running.
This training is a bit different. By using the power of mustache, gulp, and scripting, this project allows you to test two existing URLs and see the difference between them. This can be a production site and a development site, two different versions of the same site (like in the example "pages/urls.json" file, version "2.7" and "2.8" of the toolkit), or one site where you can change the content and see the effects of the change.
- NPM installed on your machine. See NPM Install Instructions
- Basic knowledge of NPM and JSON.
- (Optional) Two websites that are similar, or one websites that you can change in between two runs.
- (Optional) An IDE like Visual Studio Code.
- Clone the repository to your local machine or from this repository, choose the green "Code" button --> Download ZIP, and extract the files to your local machine.
- Run "npm install" in a command-line prompt or through your IDE to install the requirements.
- Update the "pages/urls.json" to reflect your information if you want to use your own site. Things you can change:
- The "testname" (currently "Toolkit Information"). This can be anything and is the title of your project.
- The "dev" (currently "https://cdn.toolkit.illinois.edu/2.8/"). This is your development URL. If you don't have a development site, you can use your production site. Make sure you include the final "/".
- The "prod" (currently "https://cdn.toolkit.illinois.edu/2.7/"). This is your production URL. Again, make sure you include the final "/".
- The individual items inside "urls". Note that the last one cannot have a comma at the end and needs the "last" value set to true. The label can be anything you want, and the url is the relative URL based on the prod and dev path.
- Run "npm run backstop_create_prod_screenshots" in a command-line prompt or through your IDE. This is creating the production configuration file and generating the initial reference screenshots from your production site.
- If you are using a single site, make changes to this site.
- Run "npm run backstop_test" in a command-line prompt or through your IDE. This is creating the dev configuration file and will launch a comparison report between the two sites.
Make sure your "pages/urls.json" file is proper JSON. You can use an online validator like JSONLint or use an IDE like Visual Studio to validate your JSON.
If files are not generated, make sure you aren't adding a double slash (like adding "/" at the end of the "prod" or "dev" and "/" at the beginning of the "url" field.
If your connection or the chosen site is slow, backstop may be taking a screenshot before the site is fully loaded. To change this, you can change the delay in the mustache files in the /templates folder from 0 to a larger value (this is in milliseconds, so 5000 will wait five seconds). This will affect all the pages you have chosen for the run.
If the chosen pages has video or movement on the screen, you may not be able to easily make the pages match. You can fix this using the hideSelectors option, but this is somewhat advanced.
You can look at the /backstop_files folder to see the backstop configuration files set up. These files are generated by the /pages/urls.json file plus the mustache files in /templates folder. You could probably get away with generating a single backstop configuration file (using the referenceUrl), but this allows you to see the difference between the two runs.
The /pages/urls.json also has information about the viewport. You can add or remove the viewport sizes you want to check by changing this. Again, note that the last viewport cannot have a comma at the end and needs the "last" value set to true.
Right now, the configuration options for all the pages are the same except for the label and URL. You can change this by adding additional fields in the /pages/urls.json file and extracting them in the templates using the mustache syntax. Remember that you need {{{ }}} instead of {{ }} so the infomration is not HTML encoded. Some things you may want to vary by page are the hideSelectors and misMatchThreshold values.
The package.json has the actual backstop commands. We are not using the "backstop approve" command, which you normally would use to move your test files to approval. Instead, we are using the "backstop reference" command.