Skip to content
This repository has been archived by the owner on Aug 5, 2020. It is now read-only.

Latest commit

 

History

History
125 lines (82 loc) · 4.35 KB

api.md

File metadata and controls

125 lines (82 loc) · 4.35 KB
Raw

API doc

A REST API is available to send screenshots to the VisualReview server from another process.

General structure

All calls to the API use the base url:

http://' + {{hostname}} + ':' + {{port}} + '/api/' + {{path}}

By default you should use hostname localhost and port 7000. The path depends on the end point. Generally there an endpoint supports a GET, POST and DELETE method.

End points

The API end points allow you to read and manipulate projects, suites, runs and the images within a run. Here is a non-exhaustive list of the end points and available methods.

Projects

Path: projects Methods: GET

Retrieve list of projects.

Path: projects/{{project_id}} Methods: GET, DELETE

Retrieve specific project.

Suites

Path: projects/{{project_id}}/suites/{{suite_id}} Methods: GET, DELETE

Retrieve and delete specific project.

Suite status

Path: projects/{{project_id}}/suites/{{suite_id}}/status Methods: GET

Get last run result. This is useful to poll whether a suite is working as expected. Possible values:

  • accepted
  • rejected
  • pending

Runs

Path: runs/{{run_id}} Methods: GET

Get run specific information such as startTime and branchName.

Path: runs Methods: POST

Create a new run for for {{suiteName}} in {{projectName}}. The returned JSON object contains the run id

Screenshots

Path: runs/{{run_id}}/screenshots Methods: POST

Upload a screenshot to the supplied run. The request should be just like a multi-part form post, like you're uploading a screenshot from a form. Multipart elements should be:

  • file (binary, with the screenshot png data)
  • screenshotName (plain text, containing the screenshot name)
  • properties (application/json, JSON object with image properties, see below)
  • mask (application/json, JSON object with excludeZone array for the image comparison, see below)
  • meta (application/json, JSON object with additional data about the screenshot. Can be empty).

When a screenshot is uploaded it's compared to a previously uploaded screenshot having the same screenshotName and properties. The properties object has no predefined set of keys, however we suggest including at least a screen resolution and browser as these fields will be displayed by VisualReview's GUI. For example:

properties = {
  resolution: size.width + 'x' + size.height,
  browser: 'firefox'
}

If screenshot has dynamic zones (like dateTime in a phone screenshot), you can specify a field mask which contains a array of Excludes Zones for the image comparison engine. Exclude zones have format {"height":x,"x":x,"width":x,"y":x} in the image coordinates. For Example : {"mask":{"excludeZones":[{"height":40,"x":0,"width":640,"y":0}]}}

The field metadata can contain some additional data of the screenshot. Currently it's not being used by VisualReview's GUI, but might be handy for other tools using VisualReview's API.

Analysis

Path: runs/{{run_id}}/analysis Methods: GET

Get analysis for a given run. An analysis contains an array of diffs one for each screenshot taken. Each of these diffs have an id to a before and after image as well as the difference image.

Images

Path: image/{{image_id}} Methods: GET

Get the screenshot or difference png image.

HTTP logging

(since 0.1.2) VisualReview can log incoming API request- and outgoing response-data. This greatly eases development of new tools and libraries integrating with VisualReview.

To enable HTTP logging, add the following to config.edn: :enable-http-logging true

Currently known integrations with VisualReview

The following parts/project already make use of these API calls: