API Documentation

Suite Resource

Search our documentation:

Toggle Documentation Menu

API: Suite Resource

Jump to...


List Suites

Fetch an array of all the suites in your account.

Request
GEThttps://api.ghostinspector.com/v1/suites/?apiKey=<apiKey>
Parameters
apiKey
Your API key provided in your account
Response
{
  "code": "SUCCESS",
  "data": [
    {
      "_id": "53322c9fe3db0fcd624cc0a6",
      "organization": {
        "_id": "52df0d27fbaced54db000006",
        "name": "Organization Name",
        "personal": false
      },
      "dateCreated": "2014-03-26T01:25:51.804Z",
      "variables": [],
      "screenshotCompareThreshold": 0.1,
      "screenshotCompareEnabled": true,
      "viewportSize": {
        "height": 768,
        "width": 1024
      },
      "failOnJavaScriptError": false,
      "autoRetry": true,
      "browser": "slimerjs",
      "region": "us-east-1",
      "httpHeaders": [],
      "maxConcurrentTests": 0,
      "testFrequencyAdvanced": [],
      "testFrequency": 0,
      "testCount": 3,
      "name": "Sample Suite #1"
    },
    {
      "_id": "53371f015e626de203bbb3f6",
      "organization": {
        "_id": "52df0d27fbaced54db000006",
        "name": "Organization Name"
      },
      "dateCreated": "2014-03-29T19:29:05.645Z",
      "variables": [
        {
          "name": "firstName",
          "value": "justin",
          "private": false
        },
      "screenshotCompareThreshold": 0.1,
      "screenshotCompareEnabled": true,
      "viewportSize": {
        "height": 768,
        "width": 1024
      },
      "failOnJavaScriptError": false,
      "autoRetry": true,
      "browser": "slimerjs",
      "region": "us-east-1",
      "httpHeaders": [],
      "maxConcurrentTests": 0,
      "testFrequencyAdvanced": [],
      "testFrequency": 0,
      "testCount": 2,
      "name": "Sample Suite #2"
    }
  ]
}


Get Suite

Fetch a single suite

Request
GEThttps://api.ghostinspector.com/v1/suites/<suiteId>/?apiKey=<apiKey>
Parameters
apiKey
Your API key provided in your account
suiteId
The ID of the suite to fetch
Response
{
  "code": "SUCCESS",
  "data": {
    "_id": "53371f015e626de203bbb3f6",
    "organization": {
      "_id": "52df0d27fbaced54db000006",
      "name": "Organization Name"
    },
    "dateCreated": "2014-03-29T19:29:05.645Z",
    "variables": [
      {
        "name": "firstName",
        "value": "justin",
        "private": false
      },
    "screenshotCompareThreshold": 0.1,
    "screenshotCompareEnabled": true,
    "viewportSize": {
      "height": 768,
      "width": 1024
    },
    "failOnJavaScriptError": false,
    "autoRetry": true,
    "browser": "slimerjs",
    "region": "us-east-1",
    "httpHeaders": [],
    "maxConcurrentTests": 0,
    "testFrequencyAdvanced": [],
    "testFrequency": 0,
    "testCount": 2,
    "name": "Sample Suite"
  }
}


Execute Suite

Execute all the tests in a suite and returns an array of results.

Note: We execute tests concurrently, however this request can still take some time to return. In general, it will return in the time that it takes to run your longest test; however, this can vary depending on the load on our system and the number of tests being run. We’d suggest programming your request to deal with response times up to 20 minutes. If all the suite's tests are not completed within 20 minutes, the API will send a timeout error (although your tests will still be triggered).
Request
GET or POSThttps://api.ghostinspector.com/v1/suites/<suiteId>/execute/?apiKey=<apiKey>&startUrl=<startUrl>
Parameters
apiKey
Your API key provided in your account
suiteId
The ID of the suite to execute
startUrl
(Optional) Alternate start URL to use for all tests in this execution only
browser
(Optional) Alternate browser to use for this execution. The following options are available: firefox (default), firefox-<version> specific version of Firefox, for example firefox-57, chrome (paid plans only), phantomjs
viewport
(Optional) Alternate screen size to use for all tests in this execution only. This should be a string formatted as {width}x{height}, for example 1024x768.
userAgent
(Optional) Alternate user agent to use for all tests in this execution only
region
(Optional) Geo-location for test execution. The following options are available: us-east-1 (default), us-west-1, ca-central-1, eu-central-1, eu-west-1, eu-west-2, eu-west-3, ap-northeast-1, ap-northeast-2, ap-southeast-1, ap-southeast-2, ap-south-1, sa-east-1
httpAuthUsername
(Optional) Alternate HTTP authentication username to use for this execution only
httpAuthPassword
(Optional) Alternate HTTP authentication password to use for this execution only
disableNotifications
(Optional) Use 1 to disable all notifications for this execution only
immediate
(Optional) Use 1 to initiate the execution, then immediate return a response (without results)
dataFile
(Optional) A CSV file containing a row of variable values for each suite run as outlined in our data-driven testing section. A POST request must be used when sending this file. When included, an array of suite results will be returned instead of an array of test result.
slackChannel
(Optional) Specify the Slack channel to notify for this suite run. Note that the value must be myChannel or %23myChannel and not #myChannel.
[varName]
(Optional) Pass in custom variables for the suite run that are accessible in your steps via {{varName}}. For example, including &firstName=Justin in the API call will create a {{firstName}} variable with the value Justin in each test run.
Request Examples using cURL
Note: in all cases POST variables will override GET parameters.
GET Request with Parameters:
curl https://api.ghostinspector.com/v1/suites/<suiteId>/execute/?apiKey=<key>&startUrl=<url>

POST Request with Parameters:
curl -d "apiKey=<key>" -d "startUrl=<url>" https://api.ghostinspector.com/v1/suites/<suiteId>/execute/

POST Request with JSON body:
curl -H 'Content-Type: application/json' -d '{"apiKey": "key", "startUrl": "url", "myVar": 99}' https://api.ghostinspector.com/v1/suites/<suiteId>/execute/

POST Multipart Form Request with CSV File:
curl -F "apiKey=<key>" -F "dataFile=@vars.csv" https://api.ghostinspector.com/v1/suites/<suiteId>/execute/
Response
{
  "code": "SUCCESS",
  "data": [
    {
      "_id": "5967e964d078e8ba058b2455",
      "uuid": "39e1cd5f-40e6-4e89-bba7-38f6262c5dc7",
      "test": "5967e6fbbfebc5ba07c5b0e4",
      "suiteResult": "5967e964d078e8ba058b2454",
      "name": "Test #1",
      "browser": "slimerjs-52",
      "globalStepDelay": 250,
      "maxWaitDelay": 15000,
      "maxAjaxDelay": 10000,
      "finalDelay": 5000,
      "autoRetry": true,
      "failOnJavaScriptError": false,
      "screenshotCompareEnabled": true,
      "screenshotCompareThreshold": 0.1,
      "startUrl": "https://ghostinspector.com",
      "region": "us-east-1",
      "dateCreated": "2017-07-13T21:43:00.266Z",
      "screenshotCompareDifference": 0,
      "screenshotComparePassing": true,
      "passing": true,
      "console": [],
      "urls": [
        "https://ghostinspector.com/",
        "https://ghostinspector.com/learn-more/"
      ],
      "filters": [],
      "steps": [
        {
          "command": "click",
          "target": ".site-header [href=\"/learn-more/\"]",
          "value": "",
          "variableName": "",
          "url": "https://ghostinspector.com/",
          "dateExecuted": "2017-07-13T21:43:07.665Z",
          "passing": true,
          "optional": false,
          "private": false,
          "sequence": 0
        }
      ],
      "viewportSize": {
        "height": 768,
        "width": 1024
      },
      "user": {
        "_id": "52df0d27fbaced54db000006",
        "name": "Sample User"
      },
      "dateExecutionStarted": "2017-07-13T21:43:04.334Z",
      "executionHost": "prod012.ghostinspector.net",
      "dateExecutionFinished": "2017-07-13T21:43:14.140Z",
      "endUrl": "https://ghostinspector.com/learn-more/",
      "executionTime": 9806,
      "extractions": {},
      "screenshot": {
        "original": {
          "size": 585097,
          "dims": {
            "h": 3576,
            "w": 1024
          },
          "defaultUrl": "https://ghostinspector-prod.s3.amazonaws.com/screenshots/39e1cd5f-40e6-4e89-bba7-38f6262c5dc7-original.png",
          "path": "/screenshots/39e1cd5f-40e6-4e89-bba7-38f6262c5dc7-original.png"
        },
        "small": {
          "size": 218373,
          "dims": {
            "h": 1118,
            "w": 320
          },
          "defaultUrl": "https://ghostinspector-prod.s3.amazonaws.com/screenshots/39e1cd5f-40e6-4e89-bba7-38f6262c5dc7-small.png",
          "path": "/screenshots/39e1cd5f-40e6-4e89-bba7-38f6262c5dc7-small.png"
        }
      },
      "screenshotCompareBaselineResult": "5967e733bfebc5ba07c5b0e6",
      "video": {
        "path": "/videos/39e1cd5f-40e6-4e89-bba7-38f6262c5dc7.mp4",
        "url": "https://ghostinspector-prod.s3.amazonaws.com/videos/39e1cd5f-40e6-4e89-bba7-38f6262c5dc7.mp4",
        "dims": {
          "w": 1024,
          "h": 768
        }
      },
      "testName": "Test #1"
    },
    {
      "_id": "5967e964d078e8ba058b2456",
      "uuid": "a5bf4bf2-0c20-42c9-a660-d0ab5c9cb751",
      "test": "5967e75abfebc5ba07c5b0e7",
      "suiteResult": "5967e964d078e8ba058b2454",
      "name": "Test #2",
      "browser": "slimerjs-52",
      "globalStepDelay": 250,
      "maxWaitDelay": 15000,
      "maxAjaxDelay": 10000,
      "finalDelay": 5000,
      "autoRetry": true,
      "failOnJavaScriptError": false,
      "screenshotCompareEnabled": true,
      "screenshotCompareThreshold": 0.1,
      "startUrl": "http://ghostinspector.com/docs/",
      "region": "us-east-1",
      "dateCreated": "2017-07-13T21:43:00.331Z",
      "screenshotCompareDifference": 0.002,
      "screenshotComparePassing": true,
      "passing": true,
      "console": [
        {
          "output": "Sample console error...",
          "error": false,
          "url": "https://ghostinspector.com/docs/?q=frames",
          "dateExecuted": "2017-07-13T21:43:12.268Z",
        }
      ],
      "urls": [
        "http://ghostinspector.com/docs/",
        "https://ghostinspector.com/docs/?q=frames"
      ],
      "filters": [],
      "steps": [
        {
          "command": "assign",
          "target": ".header-search-input",
          "value": "frames",
          "variableName": "",
          "url": "https://ghostinspector.com/docs/",
          "dateExecuted": "2017-07-13T21:43:11.484Z",
          "passing": true,
          "optional": false,
          "private": false,
          "sequence": 0
        },
        {
          "command": "click",
          "target": ".header-search-button",
          "value": "",
          "variableName": "",
          "url": "https://ghostinspector.com/docs/",
          "dateExecuted": "2017-07-13T21:43:11.947Z",
          "passing": true,
          "optional": false,
          "private": false,
          "sequence": 1
        },
        {
          "command": "assertTextPresent",
          "target": ".content .search-input",
          "value": "frames",
          "variableName": "",
          "url": "https://ghostinspector.com/docs/?q=frames",
          "dateExecuted": "2017-07-13T21:43:13.368Z",
          "passing": true,
          "optional": false,
          "private": false,
          "sequence": 2
        }
      ],
      "viewportSize": {
        "height": 768,
        "width": 1024
      },
      "user": {
        "_id": "52df0d27fbaced54db000006",
        "name": "Sample User"
      },
      "dateExecutionStarted": "2017-07-13T21:43:08.295Z",
      "executionHost": "prod012.ghostinspector.net",
      "dateExecutionFinished": "2017-07-13T21:43:18.982Z",
      "endUrl": "https://ghostinspector.com/docs/?q=frames",
      "executionTime": 10687,
      "extractions": {},
      "screenshot": {
        "original": {
          "size": 237230,
          "dims": {
            "h": 2232,
            "w": 1024
          },
          "defaultUrl": "https://ghostinspector-prod.s3.amazonaws.com/screenshots/a5bf4bf2-0c20-42c9-a660-d0ab5c9cb751-original.png",
          "path": "/screenshots/a5bf4bf2-0c20-42c9-a660-d0ab5c9cb751-original.png"
        },
        "small": {
          "size": 92213,
          "dims": {
            "h": 698,
            "w": 320
          },
          "defaultUrl": "https://ghostinspector-prod.s3.amazonaws.com/screenshots/a5bf4bf2-0c20-42c9-a660-d0ab5c9cb751-small.png",
          "path": "/screenshots/a5bf4bf2-0c20-42c9-a660-d0ab5c9cb751-small.png"
        }
      },
      "screenshotCompareBaselineResult": "5967e7c9bfebc5ba07c5b0eb",
      "video": {
        "path": "/videos/a5bf4bf2-0c20-42c9-a660-d0ab5c9cb751.mp4",
        "url": "https://ghostinspector-prod.s3.amazonaws.com/videos/a5bf4bf2-0c20-42c9-a660-d0ab5c9cb751.mp4",
        "dims": {
          "w": 1024,
          "h": 768
        }
      },
      "testName": "Test #2"
    }
  ]
}


Duplicate Suite

Duplicate a suite and return the new suite.

Request
GET or POSThttps://api.ghostinspector.com/v1/suites/<suiteId>/duplicate/?apiKey=<apiKey>
Parameters
apiKey
Your API key provided in your account
suiteId
The ID of the suite to duplicate
Response
{
    "code": "SUCCESS",
    "data": {
      "_id": "5a00bab816ff5929f6219918",
      "organization": {
        "_id": "52df0d27fbaced54db000006",
        "name": "Organization Name"
      },
      "dateCreated": "2017-11-04T10:29:05.645Z",
      "variables": [
        {
          "name": "firstName",
          "value": "justin",
          "private": false
        },
      "screenshotCompareThreshold": 0.1,
      "screenshotCompareEnabled": true,
      "viewportSize": {
        "height": 768,
        "width": 1024
      },
      "failOnJavaScriptError": false,
      "autoRetry": true,
      "browser": "slimerjs",
      "region": "us-east-1",
      "httpHeaders": [],
      "maxConcurrentTests": 0,
      "testFrequencyAdvanced": [],
      "testFrequency": 0,
      "testCount": 2,
      "name": "Sample Suite (Copy)"
    }
      }


Import Test

Import a test in Selenium HTML format and return the new test.

Request
POSThttps://api.ghostinspector.com/v1/suites/<suiteId>/import-test/?apiKey=<apiKey>
Parameters
apiKey
Your API key provided in your account
suiteId
The ID of the suite to duplicate
dataFile
The Selenium HTML File to import
Request Example using cURL

POST with HTML file:
curl -F "apiKey=<key>" -F "dataFile=@test.html" https://api.ghostinspector.com/v1/suites/<suiteId>/import-test/
Response
{
        "code": "SUCCESS",
        "data": [
          {
            "_id": "5967e6fbbfebc5ba07c5b0e4",
            "startUrl": "https://ghostinspector.com",
            "suite": {
              "_id": "5967e6e7bfebc5ba07c5b0e3",
              "name": "API Samples"
            },
            "organization": {
              "_id": "547fb82d92423992d52a4fea",
              "name": "Sample Organization"
            },
            "dateCreated": "2017-07-13T21:32:43.549Z",
            "dateUpdated": "2017-07-13T21:33:37.548Z",
            "dateExecutionFinished": "1970-01-01T00:00:00.000Z",
            "dateExecutionStarted": "1970-01-01T00:00:00.000Z",
            "screenshotComparePassing": null,
            "screenshotCompareThreshold": 0.1,
            "screenshotCompareEnabled": null,
            "screenshotExclusions": ".featured",
            "screenshotTarget": "#content",
            "passing": null,
            "failOnJavaScriptError": null,
            "autoRetry": null,
            "finalDelay": 5000,
            "maxAjaxDelay": 10000,
            "maxWaitDelay": 15000,
            "globalStepDelay": 250,
            "region": "us-east-1",
            "userAgent": "custom",
            "httpHeaders": [],
            "viewportSize": {
              "width": 1024,
              "height": 768
            },
            "steps": [{
              "command": "assign",
              "target": ".header-search-input",
              "value": "frames",
              "variableName": "",
              "optional": false,
              "private": false,
              "sequence": 0
            }, {
              "command": "click",
              "target": ".header-search-button",
              "value": "",
              "variableName": "",
              "optional": false,
              "private": false,
              "sequence": 1
            }, {
              "command": "assertTextPresent",
              "target": ".content .search-input",
              "value": "frames",
              "variableName": "",
              "optional": false,
              "private": false,
              "sequence": 2
            }]
            "testFrequencyAdvanced": [],
            "testFrequency": 0,
            "name": "Imported test"
          }
      }


List Suite Tests

Fetch an array of all the tests in a suite.

Request
GEThttps://api.ghostinspector.com/v1/suites/<suiteId>/tests/?apiKey=<apiKey>
Parameters
apiKey
Your API key provided in your account
suiteId
The ID of the suite containing the tests
Response
{
  "code": "SUCCESS",
  "data": [
    {
      "_id": "5967e6fbbfebc5ba07c5b0e4",
      "startUrl": "https://ghostinspector.com",
      "suite": {
        "_id": "5967e6e7bfebc5ba07c5b0e3",
        "name": "API Samples"
      },
      "organization": {
        "_id": "547fb82d92423992d52a4fea",
        "name": "Sample Organization"
      },
      "dateCreated": "2017-07-13T21:32:43.549Z",
      "dateUpdated": "2017-07-13T21:33:37.548Z",
      "dateExecutionFinished": "2017-07-13T21:43:14.140Z",
      "dateExecutionStarted": "2017-07-13T21:43:04.334Z",
      "screenshotComparePassing": true,
      "screenshotCompareThreshold": 0.1,
      "screenshotCompareEnabled": null,
      "passing": true,
      "failOnJavaScriptError": null,
      "autoRetry": null,
      "finalDelay": 5000,
      "maxAjaxDelay": 10000,
      "maxWaitDelay": 15000,
      "globalStepDelay": 250,
      "httpHeaders": [],
      "testFrequencyAdvanced": [],
      "testFrequency": 0,
      "name": "Test #1"
    },
    {
      "_id": "5967e75abfebc5ba07c5b0e7",
      "startUrl": "http://ghostinspector.com/docs/",
      "suite": {
        "_id": "5967e6e7bfebc5ba07c5b0e3",
        "name": "API Samples"
      },
      "organization": {
        "_id": "547fb82d92423992d52a4fea",
        "name": "Sample Organization"
      },
      "dateCreated": "2017-07-13T21:34:18.425Z",
      "dateUpdated": "2017-07-13T21:36:08.523Z",
      "dateExecutionFinished": "2017-07-13T21:43:18.982Z",
      "dateExecutionStarted": "2017-07-13T21:43:08.295Z",
      "screenshotComparePassing": true,
      "screenshotCompareThreshold": 0.1,
      "screenshotCompareEnabled": null,
      "passing": true,
      "failOnJavaScriptError": null,
      "autoRetry": null,
      "finalDelay": 5000,
      "maxAjaxDelay": 10000,
      "maxWaitDelay": 15000,
      "globalStepDelay": 250,
      "httpHeaders": [],
      "testFrequencyAdvanced": [],
      "testFrequency": 0,
      "name": "Test #2"
    }
  ]
}


List Suite Results

Fetch an array of suite results for a suite.

Request
GEThttps://api.ghostinspector.com/v1/suites/<suiteId>/results/?apiKey=<apiKey>
Parameters
apiKey
Your API key provided in your account
suiteId
The ID of the suite containing the results
count
The number of results to return (default 10, maximum 50)
offset
The number of results to offset the returned set by (default 0)
Response
{
  "code": "SUCCESS",
  "data": [
    {
      "_id": "5967eaeebfebc5ba07c5b0ec",
      "suite": {
        "_id": "5967e6e7bfebc5ba07c5b0e3",
        "organization": "547fb82d92423992d52a4fea",
        "name": "API Samples"
      },
      "name": "API Samples",
      "startUrl": "",
      "dateCreated": "2017-07-13T21:49:34.373Z",
      "dateExecutionFinished": "2017-07-13T21:49:59.571Z",
      "dateExecutionStarted": "2017-07-13T21:49:34.373Z",
      "executionTime": 25198,
      "countScreenshotCompareUnknown": 0,
      "countScreenshotCompareFailing": 0,
      "countScreenshotComparePassing": 2,
      "countUnknown": 0,
      "countFailing": 0,
      "countPassing": 2,
      "screenshotComparePassing": true,
      "passing": true,
      "user": {
        "_id": "52df0d27fbaced54db000006",
        "name": "Sample User"
      }
    },
    {
      "_id": "5967e964d078e8ba058b2454",
      "suite": {
        "_id": "5967e6e7bfebc5ba07c5b0e3",
        "organization": "547fb82d92423992d52a4fea",
        "name": "API Samples"
      },
      "name": "API Samples",
      "startUrl": "",
      "dateCreated": "2017-07-13T21:43:00.215Z",
      "dateExecutionFinished": "2017-07-13T21:43:25.396Z",
      "dateExecutionStarted": "2017-07-13T21:43:00.215Z",
      "executionTime": 25181,
      "countScreenshotCompareUnknown": 0,
      "countScreenshotCompareFailing": 0,
      "countScreenshotComparePassing": 2,
      "countUnknown": 0,
      "countFailing": 0,
      "countPassing": 2,
      "screenshotComparePassing": true,
      "passing": true,
      "user": {
        "_id": "52df0d27fbaced54db000006",
        "name": "Sample User"
      }
    }
  ]
}


Download Suite Tests in Selenium 1 Format (HTML)

Download a zip file of all tests in Selenium 1 format (HTML).

Request
GEThttps://api.ghostinspector.com/v1/suites/<suiteId>/export/selenium-html/?apiKey=<apiKey>
Parameters
apiKey
Your API key provided in your account
suiteId
The ID of the suite containing the tests
Response
[ Zip file containing all tests in Selenium HTML format will be returned ]


Download Suite Tests in Selenium 2 Format (JSON)

Download a zip file of all tests in Selenium 2 format (JSON).

Request
GEThttps://api.ghostinspector.com/v1/suites/<suiteId>/export/selenium-json/?apiKey=<apiKey>
Parameters
apiKey
Your API key provided in your account
suiteId
The ID of the suite containing the tests
Response
[ Zip file containing all tests in Selenium JSON format will be returned ]


Suite Status Badges

Note: Status badges are disabled by default and can be enabled under Suite Settings > Details > Enable Status Badge.

Real-time embeddable status badges for your suite. Will return the appropriate status badge image based on the current status of your last suite result.

Request
GEThttps://api.ghostinspector.com/v1/suites/<suiteId>/status-badge
Parameters
screenshot
Show the status of screenshotComparePassing for the tests in this suite.
Statuses
Passing
All tests from the last completed run of this suite passed.
Partially Failing
The last completed run of this suite had partial test failures.
Failing
All tests from the last completed run of this suite failed.
Running
Suite execution is in progress.
Unknown
The suite has no previous execution or the last execution was cancelled.
Screenshot Compare
The screenshot comparisons for this suite are passing.
Example usage
<img src="https://api.ghostinspector.com/v1/suites/<suiteId>/status-badge" title="My suite status">