Percy Anywhere
Using Percy Anywhere to integrate visual testing with any 'localhost' server or remote web app server
Percy Anywhere is a simple wrapper that allows you to easily integrate Percy's visual tests with any localhost
server or remote web app server.
Requirements:
percy-capybara
gem.poltergeist
gem, which requires PhantomJs to be installed.- A directory of compiled asset files.
- A local or remote server running the app.
Installation
Make sure you have completed Setup of your CI service first. You can also test Percy in your local development environment.
Without Bundler
You can simply install the required gems globally:
$ gem install percy-capybara
$ gem install poltergeist
With Bundler
Add the following to your Gemfile
:
source 'https://rubygems.org'
gem 'poltergeist'# Requires PhantomJs to be installed.
gem 'percy-capybara'
Then, run:
$ bundle install
Usage
Percy Anywhere does not require Rails or any test framework like RSpec. It simply uses the Capybara library and a small Ruby script you write to control a web app.
Example script
Let's create a file called snapshots.rb
:
require'percy/capybara/anywhere'
ENV['PERCY_DEBUG'] = '1'# Enable debugging output.# Configuration.
server = 'http://localhost:8080'
assets_dir = File.expand_path('../dist/assets/', __FILE__)
assets_base_url = '/'
Percy::Capybara::Anywhere.run(server, assets_dir, assets_base_url) do|page|
page.visit('/')
Percy::Capybara.snapshot(page, name:'homepage')
end
server
is a URL pointing to the local or remote host, such ashttp://localhost:8080
.assets_dir
is an absolute path to a directory of compiled static assets. These can be compiled by any asset pipeline tool, such as Webpack/Broccoli.js/etc.assets_base_url
(optional): the path where your webserver hosts compiled assets, such as/assets
. Default:/
Now, run:
$ ruby snapshots.rb
If you used the Bundler installation method, run:
$ bundle exec ruby snapshots.rb
Done! 🚀 Each time the script is run, Percy snapshots are taken and uploaded for rendering and processing. The script will output a link to the build to view any visual diffs.
Interacting with elements
This script can be expanded with any complex behavior that interacts with the page. You can use all of the available Capybara actions to interact with the page.
Clicking on a button
page.visit('/')
page.click_button('New Project')
Percy::Capybara.snapshot(page, name:'homepage - new project modal')
Clicking on an element by selector
page.visit('/about')
page.find('#locations').click
Percy::Capybara.snapshot(page, name: 'about page - locations')
See the Capybara docs for many more interactions, best practices, and usage examples.
Waiting for elements
Responsive visual diffs
You can use Percy responsive visual diffs to test pages at different CSS breakpoints.
Simply set the default breakpoint configuration:
Percy.config.default_widths = [375, 1280]
With the above configuration, all snapshots will render at both mobile and desktop breakpoints by default.
You can also override widths per-snapshot:
Percy::Capybara.snapshot(page, name:'homepage', widths: [375, 1280])
Example app
A working example of this setup can be found here: https://github.com/percy/example-percy-anywhere
Other resources
Updated over 5 years ago