Home

Getting started

This guide explains how to use Urnerys. It assumes that you have an Urnerys instance set up, but requires no other prerequisites.

Urnerys is created with an API-first approach. Not all functionality is accessible thorugh the web interface. All the code examples below are using curl to interact with the API.

The purpose of this guide is to show you what APIs Urnerys offers and how to use them. More detailed guides for specific web frameworks or languages, and integrations (such as GitHub) will be available later.

The steps this guide walks you through are:

  1. Create a new project
  2. Create a new build
  3. Add images to a build
  4. Set a baseline
  5. Check a build against a baseline
  6. Inspect differences between two builds

Create a new project

The only input that is required is a project id. The example below is using the value my-project-id.

curl -X POST
  -d '{"id": "my-project-id","project": { }}'
  https://<urnerys>/api/v1/projects

Create a new build

A build groups a set of images. It corresponds roughly to a version of your code, or a deployed artefact.

A good choice for the Build ID is the commit hash, or GitHub Action run ID, Vercel deployment ID or similar unique identifiers.

curl -X POST
  -d '{"id": "build-1","build": { }}'
  https://<urnerys>/api/v1/projects/my-project-id/builds

Add images to a build

Images within a build are organized into collections, snapshots, and formulas. See [here] for recommendations how to best organize your images.

The API to upload images requires a multipart/form-data request. The image has to be in either JPEG or PNG format.

curl -X POST
  -H "Content-Type: multipart/form-data"
  -F "collection=some/folder"
  -F "snapshot=home-page"
  -F "formula=desktop"
  -F "payload=@/path/to/your/image.jpg"
  https://<urnerys>/api/v1/projects/my-project-id/builds/build-id/images

Set a baseline

A baseline is a pointer to a specific build. The build to which a baseline points to can change over time. One common baseline that most projects will have is something like production.

curl -X POST
  -d '{"id":"production","baseline":{"build":"projects/my-project-id/builds/build-id"}}'
  https://<urnerys>/api/v1/projects/my-project-id/baselines

To update a baseline to point to a different build, send a PATCH request.

curl -X PATCH
  -d '{"baseline":{"build":"projects/my-project-id/builds/build-id"}}'
  https://<urnerys>/api/v1/projects/my-project-id/baselines/production

Check a build against a baseline

When all images in a build are added, you can initiate a check of that build against a baseline. This will compare the two builds and generate a report how many images are equal or different.

If your Urnerys instance is properly integrated with GitHub, the result will be posted to GitHub as a commit check.

curl -X POST
  -d '{"check":{"baseline":"production"}}'
  https://<urnerys>/api/v1/projects/my-project-id/builds/build-id/checks

Inspect differences between two builds

To visually inspect the differences between two builds, you can pull up a web view that compares two builds. This view will highlight how many images are different between the two builds (if any). You can also approve the changes directly from the web UI if the changes were intentional.

https://<urnerys>/<project-id>/compare/<build-A-id>...<build-B-id>