### [Percy::Client on GitHub ](🔗)

[](🔗) [](🔗)

Ruby API client library for [Percy](🔗).

📘



NOTE: This is the low-level Percy API client---you probably want to use the [Capybara client](🔗) or the Ruby [command-line interface](🔗) instead.

# Installation

Add this line to your application's Gemfile:

And then run:

Or install it yourself with `gem install percy-client`.

# Authentication

Alternatively, you can set the `PERCY_TOKEN` environment variable. Each repository has it's own write-only token, which can be found in Percy _Settings_ page for the repo.

# Usage

There are four steps to working with Percy:

1. Create a build.

2. Create a snapshot for each HTML page, and indicate the resources that this page loads.

3. Upload any missing resources.

4. Finalize the build.

### Create a build

Or, to use the current Git repository name:

## Create a snapshot

The `is_root: true` param indicates the resource that is the main HTML resource of this snapshot, ie. the page that should be rendered. There must be exactly one root resource in a snapshot.

The API will automatically guess the resource mimetype based on the extension. If the URL doesn't have an extension, you can pass the `mimetype: 'text/html'` param to the `Percy::Client::Resource` object to explicitly set it.

Unlike calling `finalize_build` later, the call to `finalize_snapshot` is not strictly required. It is recommended, however, so that Percy can start processing the snapshot earlier and the build can be processed faster. If not called, Percy will wait to process snapshots until the build is finalized.

## Upload any missing resources

For performance reasons, resources are uploaded after the snapshot is created. Each snapshot API call returns a list of resource SHAs that have never been uploaded before and the client must followup and upload all the "missing" resources. This way, resources are only ever uploaded once and never re-uploaded unless they change.

The client uploads the "missing" resources:

## Finalize the build

Once all missing resources from all snapshots are uploaded, the client can finalize the build.

Done! After this, the build will finishing processing, creating screenshots and visual diffs, and the build can be viewed in Percy.

# Environment variables

You can set Percy [Environment variables](🔗) and they will override environment discovery.

# Changelog

• [percy-client releases on GitHub](🔗)

# Contributing

1. Fork it (<https://github.com/percy/percy-client/fork>)

2. Create your feature branch (`git checkout -b my-new-feature`)

3. Commit your changes (`git commit -am 'Add some feature'`)

4. Push to the branch (`git push origin my-new-feature`)

5. Create a new Pull Request