Repository files navigation

Example app showing integration ofPercy visual testinginto Ruby Selenium tests.

• selenium-webdriver: 4.36.0
• percy-selenium: 1.1.1
• @percy/cli: 1.31.2
• todomvc-app-css: 2.4.3

Based on theTodoMVCVanillaJSapp, forked at commit4e301c7014093505dcf6678c8f97a5e8dee2d250.

This tutorial assumes that you're already familiar with Ruby & Selenium and focuses on using themwith Percy. You'll still be able to follow along if you're not familiar with Ruby & Selenium, butwe won't spend time introducing concepts.

This tutorial also assumes you have Ruby, Node, Make, and git installed.

Clone the example application and install dependencies:

$ git clone https://github.com/percy/example-percy-ruby-selenium.git$cd example-percy-ruby-selenium$ make install

The example app and it's tests will now be ready to go. You can explore the app by runningmake serve and then openinglocalhost:8000 in a browser.

Sign in to Percy and create a new project. You can name the project "todo" if you'd like. Afteryou've created the project, you'll be shown a token environment variable.

In the shell window you're working in, export the token environment variable:

Unix

$export PERCY_TOKEN="<your token here>"

Windows

$set PERCY_TOKEN="<your token here>"# PowerShell$$Env:PERCY_TOKEN="<your token here>"

Note: Usually this would only be set up in your CI environment, but to keep things simple we'llconfigure it in your shell so that Percy is enabled in your local environment.

Check out a new branch for your work in this tutorial (we'll call this branchtutorial-example), then run tests & take snapshots:

$ git checkout -b tutorial-example$ maketest

This will run the app's Selenium tests, which contain calls to create Percy snapshots. The snapshotswill then be uploaded to Percy for comparison. Percy will use the Percy token you used inStep 2to know which organization and project to upload the snapshots to.

You can view the screenshots in Percy now if you want, but there will be no visual comparisonsyet. You'll see that Percy shows you that these snapshots come from yourtutorial-example branch.

Use your text editor to editindex.html and introduce some visual changes. For example, you canadd inline CSS to bold the "Clear completed" button on line 32. After the change, that line lookslike this:

<buttonclass="clear-completed"style="font-weight:bold">Clear completed</button>

Commit the change:

$ git commit -am"Emphasize 'Clear completed' button"

Run the tests with snapshots again:

$ maketest

This will run the tests again and take new snapshots of our modified application. The new snapshotswill be uploaded to Percy and compared with the previous snapshots, showing any visual diffs.

At the end of the test run output, you will see logs from Percy confirming that the snapshots weresuccessfully uploaded and giving you a direct URL to check out any visual diffs.

Visit your project in Percy and you'll see a new build with the visual comparisons between the tworuns. Click anywhere on the Build 2 row. You can see the original snapshots on the left, and the newsnapshots on the right.

Percy has highlighted what's changed visually in the app! Snapshots with the largest changes areshown first You can click on the highlight to reveal the underlying screenshot.

If you scroll down, you'll see that no other test cases were impacted by our changes to the 'Clearcompleted' button. The unchanged snapshots appear grouped together at the bottom of the list.

From here, you can try making your own changes to the app and tests, if you like. If you do, re-runthe tests and you'll see any visual changes reflected in Percy.