Integrating Codeship Pro and Docker with Percy Visual Testing

Source: documentation.codeship.com

What Is Percy?

Percy is a visual testing tool that integrates into your CI/CD pipeline to capture screenshots of your application, track visual changes between builds, and require explicit team approval before visual regressions are accepted. When combined with Codeship Pro and Docker, Percy lets you automate visual regression detection as a first-class step in your delivery workflow.

Setting Up Percy with Codeship Pro

The integration relies on two components working together: Percy’s SDK (which varies by project type) installed inside your Docker image, and Percy’s API credentials passed in as encrypted environment variables in Codeship Pro.

Setting Your Percy Environment Variables

When you create a new project inside Percy, the platform provides two credential values:

• PERCY_TOKEN — the API token that authenticates your builds with Percy.
• PERCY_PROJECT — the unique identifier for your Percy project.

Both values must be added as encrypted environment variables in your codeship-services.yml file. Codeship Pro’s encrypted environment variable support ensures these secrets are never stored in plain text in your repository. Refer to the Codeship Pro environment variables documentation for instructions on encrypting and referencing these values.

Integration by Project Type

Static Sites

For static HTML sites running inside Docker images on Codeship Pro, Percy provides a CLI tool distributed as a Ruby gem. Install it in your Dockerfile:

RUN gem install percy-cli

Prerequisite: Your Docker image must include both Ruby and RubyGems. Without them, the gem installation step will fail.

Once the gem is installed, add a Percy snapshot step to your codeship-steps.yml file:

- service: your_service
  command: percy snapshot directory_to_snapshot

A few important details about this command:

• Replace your_service with the name of the service defined in your codeship-services.yml.
• Replace directory_to_snapshot with the path to the directory containing your built static files.
• The target directory must contain HTML files — Percy uses them to render the snapshots.
• You can add multiple snapshot steps to cover multiple directories in one build.

Ruby Projects

For Ruby applications using Capybara, Minitest, RSpec, or similar test frameworks, Percy provides the percy-capybara gem. Add it to your Dockerfile:

RUN gem install percy-capybara

Alternatively, add percy-capybara to your Gemfile and let Bundler manage the dependency — this is typically the cleaner approach for Ruby projects.

Prerequisite: As with static sites, your Docker image must include both Ruby and RubyGems.

After installation, you need to add Percy hooks directly into your test specs. The specific integration code — such as calling Percy::Capybara.snapshot within your tests — is documented in detail in the Percy documentation for each supported test framework. Your test suite is then invoked via the standard command step in codeship-steps.yml, and Percy captures snapshots automatically as tests run.

Ember Projects

For Ember.js applications, Percy provides a dedicated Ember addon. Install it inside your Docker image by adding the following to your Dockerfile:

RUN ember install ember-percy

As with the Ruby integration, you will need to add Percy hooks to your Ember test specs. Consult the Percy documentation for the specific API calls required to trigger snapshots within your Ember tests. Your test suite is then invoked via your codeship-steps.yml file as a normal build step, and Percy captures visual snapshots during the test run.

How the Full Pipeline Fits Together

Regardless of project type, the overall integration pattern in Codeship Pro is consistent:

1. Build your Docker image with the appropriate Percy SDK installed.
2. Encrypt your Percy credentials (PERCY_TOKEN and PERCY_PROJECT) and reference them in codeship-services.yml.
3. Run your tests or snapshot command as a step in codeship-steps.yml.
4. Review visual diffs in the Percy dashboard, where your team can approve or reject detected changes before the build is considered passing.

This workflow ensures that visual regressions are caught automatically in CI, and that no unreviewed UI change can silently reach production.

Further Reading

• Percy documentation — SDK setup guides for all supported frameworks.
• Codeship Pro documentation — reference for codeship-services.yml and codeship-steps.yml.