Photo by Ken Treloar on Unsplash.
The problem
Your development team delivers lots of changes to client facing application. For the most part, developers don't know when they've broken anything on the UI. You ship UI changes with less confidence not knowing if something broke. Whereas there are decent code review, manual QA and test coverage, they are still not enough to catch all UI bugs. One option is to go all out to engage more manual QA personnel. Alternatively, find a scalable way of integrating automated visual reviews with immediate feedback cycle to improve the whole process and ship with confidence.
There're a few reasons for visual reviews:
- Manual QA is not scalable
- Visual regression testing is a life saver
- Automated feedback is a great gain
- Cross-browser compatibility issues still live
Why Percy
I think percy does a great job on the above issues. It integrates with your existing CI workflow, highlights visual diffs across browsers, screens and snapshots. The icing on the cake is the ability to review and approve these changes. Basically, Percy combines visual testings and review platform in one which is pretty cool.
As, at the time of this writing, Percy is free for up to 5k snapshots monthly.
Let's walk through how to use Percy
I'd be integrating this to the repository that powers my personal website. It's made with Gatsby and deployed to Netlify.
So, let's first clone the repository
git clone https://github.com/rowlandekemezie/rowlandekemezie.com.git
Run Percy locally
You can configure percy-cli for testing locally
$ gem install percy-cli
Before we proceed, we'll need a PERCY_TOKEN which is write-only API key that only has access to create builds, snapshots, and upload resources to this project. So, signup on percy with your GitHub account.
Next, create an organization name, confirmation email and click Start new project.
Next up is to add a project to your organization. Probably, a good idea to use the repository name.
All is set. Now, you have your PERCY_TOKEN which will be used for running the test locally and on CI.
Let's get back to the terminal to test it out locally with the token
Ensure you run yarn build first.
Click on the link generated below to review it on Percy platform.
The left column is blank because there's no snapshot to compare against yet.
Integrate Percy with your CI workflow
We'll love to integrate Percy to our CI workflow. It should run on every commit.
Let's use CircleCI for this. However, it works just fine with every other supported CI platform.
First, let's set up the project on CircleCI. login/signup to CircleCI with your GitHub account.
Click on ADD PROJECTS on the sidebar and then click on Set Up Project button for the project of choice.
We'll keep the default setting on the next page(Linux and Node) and follow other instructions.
Next up, create .circleci/config.yml in the root directory and populate with
version: 2
defaults: &defaults
docker:
- image: circleci/node:10.15.1
working_directory: ~/repo
jobs:
# install: ...
# lint: ...
visual:
- image: circleci/ruby:2.6.2-node-browsers
working_directory: ~/repo
steps:
- checkout
- run:
name: install dependencies
command: |
yarn install
gem install percy-cli
- run:
name: Run visual test
command: |
yarn build
percy snapshot public
workflows:
version: 2
# test: ...
visual-test:
jobs:
- visual
I commented out few some jobs already existing in the project to help us focus on the scope of this article. When you're done testing, feel free to uncomment them 👌.
Commit and push your code to master. Head over to CircleCI click Start building. Hopefully, this is successful 👍
The build succeeds but because PERCY_TOKEN was not provided, the snapshots won't be pushed to percy.io for our review.
Let's fix it...
The same way we ran Percy locally with the PERCY_TOKEN, we'll add it to the environment variables. So, click on the settings Icon
Click on Environment variables in the sidebar to add your token
.
Commit your changes and push to master again.
Now, we can head to percy.io to see the snapshots created by the build.
Percy automatically detects that there's no change hence, "All changes approved automatically on this branch".
Link up Percy to your repository
The final part of this setup is to link Percy to our repository to get immediate feedback after each build.
In the project setting on Percy, click on install an integration and choose GitHub.
Here you go...
Select the repository you want to install Percy and click install.
With the source code integration enabled, we can manage our pull request statuses, notifying us when visual changes are detected. It also gives a nice interface to approve those changes with the record of who approved the pull request.
Now you can select the repository to link to each project
End to end test
Now, let's test everything together. Let's create a test branch and increase the font-size of the content's title in /components/Post/Content/Content.module.scss. Commit the change and create a pull request.
......
.content {
&__title {
font-size: $typographic-base-font-size * 4; /* change font-size */
max-width: $layout-post-width;
......
......
}
This is a fantastic part of it. There are a whopping 15 visual changes introduced by the font-size change.
You can click on details to take us straight to Percy to compare the changes
The red font-colour on the right column only show the area of the UI affected by the change(s). You can click on it to see the actual changes.
We can approve the changes by clicking Approve all and boom all checks passed ✅
Percy gives you and your team the power to review and approve UI changes with confidence. You can build toolings around the capabilities it provides.
Further reading
This post was originally published on my website. Consider subscribing to my newsletter for updates. No spam!
Top comments (0)