Skip to content
A simple UI for browsing and inspecting diffs, and an API for runner scripts to submit screenshots to and receive a pass or fail in real time. (For use with Wraith, Backstop, Selenium etc)
Ruby HTML JavaScript CSS Dockerfile Gherkin Shell
Branch: master
Clone or download

Latest commit

Latest commit a909c9f May 8, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
app crop_area param support implemented (#38) Jun 14, 2017
bin Finish upgrade to Rails 5.0 Apr 29, 2019
config Updates ruby to 2.7.1, bundler to 2.1.4 May 7, 2020
db crop_area param support implemented (#38) Jun 14, 2017
features Travis CI build Feb 9, 2017
lib crop_area param support implemented (#38) Jun 14, 2017
log Initial commit Jan 5, 2016
public Add favicon and use as a logo for now Mar 8, 2016
script add puma server Apr 29, 2019
spec crop_area param support implemented (#38) Jun 14, 2017
tmp Add tmp directory for tests to run Feb 9, 2017
vendor/assets Initial commit Jan 5, 2016
.dockerignore Added Docker support :) (#16) Jun 15, 2016
.gitignore Dockerize properly, and update README Feb 7, 2017
.rspec use rails rspec Feb 10, 2016
.ruby-version Updates ruby to 2.7.1, bundler to 2.1.4 May 7, 2020
.travis.yml Updates ruby to 2.7.1, bundler to 2.1.4 May 7, 2020
Dockerfile Merge pull request #84 from wearefriday/bump-ruby-version May 8, 2020
Gemfile Add S3 as storage option Apr 21, 2020
Gemfile.lock Merge pull request #82 from wearefriday/dependabot/bundler/rack-2.2.2 May 8, 2020
LICENSE Add MIT licence Sep 28, 2016 Updates ruby to 2.7.1, bundler to 2.1.4 May 7, 2020
Rakefile Travis CI build Feb 9, 2017
app.json Add "Deploy to Heroku" button for easy set up (#17) Sep 20, 2016 Initial commit Jan 5, 2016
docker-compose.yml Updates ruby to 2.7.1, bundler to 2.1.4 May 7, 2020
spectre_screenshot_1.png Readme update Jun 1, 2016
spectre_screenshot_2.png Readme update Jun 1, 2016


Build Status

Spectre is a web application to diff screenshots. It's heavily influenced by VisualReview, BackstopJS and Wraith. Read more about how we use it at Friday in our blog post: How we do visual regression testing.

Spectre! Spectre!

Running the app

You can either run the app using docker, or you can run it natively on your machine – there are instructions for both docker, and running on macOS below.

Alternatively, you can run the application on Heroku.

Running using docker

Install docker

Setup the database (only needs to be done once):

docker-compose run --rm app bundle exec rake db:setup

To run the application:

docker-compose up

When you see WEBrick::HTTPServer#start: pid=2 port=3000, the app will be running at http://localhost:3000

Running natively on macOS


  • Ruby (doesn't currently work with v2.4.0)
  • Postgres
  • Imagemagick

On a Mac, the easiest way to install the above, is to use homebrew.

  1. install homebrew using these instructions
  2. brew install rbenv
  3. rbenv install 2.7.1
  4. rbenv init and follow the instructions it prints
  5. brew install imagemagick@6
  6. brew install postgresql and follow the instructions it prints about starting the postgresql server


  • Clone the repo
  • bundle install && bundle exec rake db:setup
  • bundle exec rails s

Running on Heroku:

Deploy to Heroku

Submitting tests

A "test" is a screenshot and associated metadata. A test is categorised under a Project, which in turn has (test) Suites. A test is submitted and associated with a "run" of a suite.

First you should create a new "run". The JSON response will contain the run_id to submit with each subsequent test.

POST /runs
  project: My Project Name
  suite: My Suite Name

Then you can submit a screenshot!

POST /tests
    run_id: {run_id from above},
    name: Homepage,
    platform: OSX,
    browser: PhantomJS,
    size: 1024,
    screenshot: <File>,
    crop_area: '640x480+50+100'
  • name is a friendly name of your test. It should describe the template, component or state of the thing you've screenshotted
  • platform is the OS/platform that the screenshot was taken on (e.g. OSX, Windows, iOS, Android etc.)
  • browser is the browser that was used to render the screenshot. This will usually be a headless webkit such as Phantom, but if using Selenium you may have used a "real" browser
  • size is the screenshot size
  • screenshot is the image itself. PNGs are preferred
  • crop_area allows to specify a bounding box to crop from uploaded screenshot ("x+<top_left_x>+<top_left_y>"). If not specified, full screenshot is used for comparison. Can be used to perform visual diffs for specific page elements.

Integration with Rake tasks or Cucumber

Most of the time you'll want to use your own rake task to control Selenium and take screenshots, or take screenshots during cucumber step definitions. There's a handy spectre_client gem to upload screenshots to your Spectre gem.

Example test run

An example test run can be executed using:

docker-compose run --rm app bin/demo_test_run http://app:3000

or, if not using docker, first install phantomjs (brew install phantomjs), then run:

bin/demo_test_run http://localhost:3000

If you've deployed the app on heroku, you can replace the URL with the hosted one, e.g.:

docker-compose run --rm app bin/demo_test_run
# or


Spectre doesn't provide a UI or API to edit or delete content. We've included rails_admin, so head to /admin for this. By default there is no password.



Rspec and Cucumber are included in the project. Test coverage is minimal but please don't follow our lead, write tests for anything you add. Use rake to run the existing tests.

You can’t perform that action at this time.