Introduction
Welcome to the CucumberStudio API! You can use our API endpoints to get information on your projects in our database. It is RESTful and follows the {json:api} specification.
Since we don't provide integration with any programming languages (yet!), the examples are written in shell, using the curl command.
Our API documentation was created with Slate.
API rate limits
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Your application can make up to 200 API requests per minute.
Once the limit is exceeded, clients receive an HTTP 429 with a Retry-After: X
header to indicate how long their timeout period is before they will be able to
send requests again. The timeout period is set to 60 seconds once the limit is
exceeded.
Note
The rate limit is based on the IP address.
Getting Started
This little tutorial will guide you to request our API for the first time.
Your API credentials
Before accessing our API you need to generate your API credentials. Sign in to
your account on CucumberStudio then go to
your profile page. Click the
Generate new API credentials button.
Your first request
Replace
$PROJECT_ID,$ACCESS_TOKEN,$CLIENT_IDand$UIDwith yours
GET https://studio.cucumber.io/api/projects/$PROJECT_ID/scenarios HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: $ACCESS_TOKEN
client: $CLIENT_ID
uid: $UID
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "scenarios",
"id": "668555",
"attributes": {
"name": "Card has been disabled (1)",
"description": "An error is displayed when the cart has been disabled"
},
"links": {
"self": "/scenarios/668555"
}
},
{
"type": "scenarios",
"id": "668556",
"attributes": {
"name": "Account has sufficient funds for transferring cash (1)",
"description": ""
},
"links": {
"self": "/scenarios/668556"
}
}
]
}
For your first request, you'll need your API credentials, and a project ID. All the API endpoints depend on a project. You can retrieve their ID in the address bar of your browser while you are viewing the dashboard of your project.
In the following example we are looking for the ID of the sample project
Testing CASH WITHDRAWAL: the ID is 116088.
Now to retrieve all the scenarios of your project use the endpoint
api/projects/$PROJECT_ID/scenarios. The HTTP call looks
like the following:
GET https://studio.cucumber.io/api/projects/$PROJECT_ID/scenarios
Replace the $PROJECT_ID with the ID of one of your project. The following headers MUST be part of the query:
Accept: application/vnd.api+json; version=1access-token: $ACCESS_TOKEN(replace $ACCESS_TOKEN with your access token)client: $CLIENT_ID(replace $CLIENT_ID with your client ID)uid: $UID(replace $UID with your UID)
Every requests to the API must include those 4 headers.
The access token, the client ID and the UID are your API Credentials.
The header Accept tells the API to respond using the
{json:api} format and asks for the version 1 of the API.
Renewing your API Credentials
Replace
$EMAIL_ADDRESSand$PASSWORDwith your CucumberStudio credentials
POST https://studio.cucumber.io/api/auth/sign_in HTTP/1.1
Content-Type: application/json
{"email": "$EMAIL_ADDRESS", "password": "$PASSWORD"}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
access-token: iHr2dTV-UBK3Xa9vXOXERA
token-type: Bearer
client: TscNP_R2vdAV-yQc8ZjftQ
expiry: 1518274095
uid: ...@...
{
"data": [
{
...
}
]
}
Your access token, as explain on your profile page after it has been generated,
will expire. You can generate a new one on your profile page by clicking the
Generate new API credentials button again, but it is also possible to manage
it programmaticaly, using the API.
To generate or renew your API credentials use this endpoint: api/auth/sign_in.
POST https://studio.cucumber.io/api/auth/sign_in
Post your CucumberStudio credentials (email and password) encoded as JSON. If
you have been successfully authenticated your API credentials will be in the
response headers within the keys access-token, client and uid. The
expiry header is the expiration timestamp of your new token.
Authentication
To get your credentials:
POST https://studio.cucumber.io/api/auth/sign_in HTTP/1.1
Content-Type: application/json
{"email": "my_cucumberstudio_account", "password": "my_cucumberstudio_account"}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
access-token: sUaWO8m8v5Lkv5pxnLCXzA
token-type: Bearer
client: AfLp4PsN9ZieqHas-X5lrA
expiry: 1486047985
uid: my_cucumberstudio_account
An API call example
GET https://studio.cucumber.io/api/<endpoint> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Before sending requests to our endpoints, you need an authentication token. This token is made up of three data:
- The access-token
- Your client id
- Your uid
You can get this authentication token using the auth/sign_in endpoint
(only working if you registered to CucumberStudio using your email) or directly
in your CucumberStudio profile page.
CucumberStudio expects for the authentication token to be included in all API requests to the server, in the HTTP headers of your requests
Useful information about the access-token
- The token lifespan is set to a year. After that, you won't be able to access to the API anymore. Don't forget to generate a new token before the expiration date and to update your scripts
- The expiration date is returned on every HTTP response in the
expiryHTTP header. The expiry date is in POSIX timestamp format (number of seconds elapsed since 1 January 1970 00:00:00 UTC). Example:expiry: 1486047985. - You can use up to ten authentication tokens at the same time, with different clients
Projects
Get projects
GET https://studio.cucumber.io/api/projects/ HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "projects",
"id": "1",
"attributes": {
"created-at": "2017-10-02T12:01:27.125Z",
"updated-at": "2018-01-10T14:55:49.848Z",
"last-author": "harry@example.org",
"name": "And the Philosopher's Stone",
"description": "This is where all starts",
"bdd-mode": true
},
"links": {
"self": "/projects/1"
},
"relationships": {
"scenarios-folder": {
"links": {
"self": "/projects/1/relationships/scenarios-folder",
"related": "/projects/1/scenarios-folder"
}
}
}
},
{
"type": "projects",
"id": "2",
"attributes": {
"created-at": "2017-10-02T12:01:27.125Z",
"updated-at": "2018-01-10T14:55:49.848Z",
"last-author": "harry@example.org",
"name": "And the Chamber of Secrets",
"description": "With douchebag Draco Malfoy...",
"bdd-mode": false
},
"links": {
"self": "/projects/2"
},
"relationships": {
"scenarios-folder": {
"links": {
"self": "/projects/2/relationships/scenarios-folder",
"related": "/projects/2/scenarios-folder"
}
}
}
}
]
}
This endpoint retrieves all projects of the logged-in user
Get a particular project
GET https://studio.cucumber.io/api/projects/<project_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "projects",
"id": "1",
"attributes": {
"created-at": "2017-10-02T12:01:27.125Z",
"updated-at": "2018-01-10T14:55:49.848Z",
"last-author": "harry@example.org",
"name": "And the Philosopher's Stone",
"description": "This is where all starts",
"bdd-mode": true
},
"links": {
"self": "/projects/1"
},
"relationships": {
"scenarios-folder": {
"links": {
"self": "/projects/1/relationships/scenarios-folder",
"related": "/projects/1/scenarios-folder"
}
}
}
}
]
}
This endpoint retrieves a specific project of the logged-in user
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve |
Create a project backup
Create the project backup
POST https://studio.cucumber.io/api/projects/<project_id>/backups HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "projects",
"id": "1",
"attributes": {
"created-at": "2017-10-02T12:01:27.125Z",
"updated-at": "2018-01-10T14:55:49.848Z",
"last-author": "harry@example.org",
"name": "And the Philosopher's Stone",
"description": "This is where all starts",
"bdd-mode": true,
"new-backup-in-progress": true
},
"links": {
"self": "/projects/1"
},
"relationships": {
"scenarios-folder": {
"links": {
"self": "/projects/1/relationships/scenarios-folder",
"related": "/projects/1/scenarios-folder"
}
}
}
}
]
}
This endpoint will schedule the backup creation of a given project. The
operation is acknownledged with a 202 Accepted HTTP code. The returned project
attributes include a "new-backup-in-progress" field set to true.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to create the backup for |
Get last backup state
GET https://studio.cucumber.io/api/projects/<project_id>/backups/last HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "backups",
"id": "9876",
"attributes": {
"project-id": 1234,
"new-backup-in-progress": false,
"updated-at": "2018-06-13T13:19:28.380Z",
"file-name": "coffee_machine__hiptest_publisher_sample_20180419.zip",
"file-size": 33968,
"url": "https://attachments-hiptest-production.s3.amazonaws.com/backups/backup_files/000/012/345/original/coffee_machine__hiptest_publisher_sample_20180419.zip?AWSAccessKeyId=XXXXX&Expires=1528298175&Signature=XXX"
},
"links": {
"self": "/backups/9876"
}
}
}
This endpoint is useful to track the state of a project backup creation and get the last created backup URL.
If the project does not have any backups yet, or when the very first backup is in
progress, this endpoint will respond with empty data: { "data": null }.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to see the last backup of |
Getting root scenarios folder of a project
GET https://studio.cucumber.io/api/projects?include=scenarios-folder HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Also works when retrieving a single project
You can use the JSONAPI include syntax to fetch the scenarios root folder of your project
Action words
Get action words of a given project
GET https://studio.cucumber.io/api/projects/<project_id>/actionwords HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "actionwords",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"definition": "actionword 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n",
"errors": []
},
"links": {
"self": "/actionwords/1"
}
},
{
"type": "actionwords",
"id": "2",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Defeat Voldemort",
"description": "And save the world, hurray!",
"definition": "actionword 'Defeat Voldemort' do\nend\n",
"errors": []
},
"links": {
"self": "/actionwords/2"
}
}
]
}
This endpoint retrieves all action words of a given project.
You can retrieve tags of an action word from the tags endpoint.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the actionwords from |
Find actionwords by tags
Find actionwords by tags key
GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/find_by_tags?key=<tag_key> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "actionwords",
"id": "2585231",
"attributes": {
"created-at": "2019-05-02T19:21:58.344Z",
"updated-at": "2019-12-02T14:07:01.018Z",
"last-author": "harry@example.org",
"name": "I handle coffee grounds",
"description": "",
"definition": "actionword 'I handle coffee grounds' do\nend\n",
"is-shared": false,
"is-outdated": false,
"errors": []
},
"links": {
"self": "/actionwords/2585231"
},
"relationships": {
"tags": {},
"callers": {}
}
},
{
"type": "actionwords",
"id": "2585234",
"attributes": {
"created-at": "2019-05-02T19:21:58.587Z",
"updated-at": "2019-12-02T14:06:29.856Z",
"last-author": "harry@example.org",
"name": "displayed message is:",
"description": "",
"definition": "actionword 'displayed message is:' (__free_text = \"\") do\n call 'message \"message\" should be displayed' (message = __free_text)\nend\n",
"is-shared": false,
"is-outdated": false,
"errors": []
},
"links": {
"self": "/actionwords/2585234"
},
"relationships": {
"tags": {},
"callers": {}
}
}
],
"included": []
}
Find actionwords by tags key and value
GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/find_by_tags?key=<tag_key>&value=<tag_value> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "actionwords",
"id": "2585234",
"attributes": {
"created-at": "2019-05-02T19:21:58.587Z",
"updated-at": "2019-12-02T14:06:29.856Z",
"last-author": "harry@example.org",
"name": "displayed message is:",
"description": "",
"definition": "actionword 'displayed message is:' (__free_text = \"\") do\n call 'message \"message\" should be displayed' (message = __free_text)\nend\n",
"is-shared": false,
"is-outdated": false,
"errors": []
},
"links": {
"self": "/actionwords/2585234"
},
"relationships": {
"tags": {},
"callers": {}
}
}
],
"included": []
}
This endpoint retrieves all actionwords of a given project and having the given tag.
| Field name | Description |
|---|---|
| tag_key | The KEY of the tag you use to retrieve the actionwords |
| tag_value | The VALUE of the tag you use to retrieve the actionwords |
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the actionwords from |
Request parameters
| Parameter | Description |
|---|---|
| key | The key of the tag |
| value | The value of the tag |
Get a single action word
GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "actionwords",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"definition": "actionword 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n",
"errors": []
},
"links": {
"self": "/actionwords/1"
}
}
}
This endpoint retrieves a single action word of a given project.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the actionword from |
| actionword_id | The ID of the action word you want to get |
Create an action word
POST https://studio.cucumber.io/api/projects/<project_id>/actionwords HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"definition": "step {action: \"Find the last one\"}\n step {result: \"Found it!\"}"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data":
{
"type": "actionwords",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"definition": "actionword 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n",
"errors": []
},
"links": {
"self": "/actionwords/1"
}
}
}
This endpoint create new action word.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project in wich you want to create the actionword |
Mandatory fields
| Field | Description |
|---|---|
| name | (String) The name of the action word. |
Other fields
| Field | Description |
|---|---|
| description | (String) The description of the action word. |
| definition | (String) The body of the definition of the action word. |
Update an action word
PATCH https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "actionwords",
"id": <actionword_id>,
"attributes": {
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"definition": "actionword 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "actionwords",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"definition": "actionword 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n",
"errors": []
},
"links": {
"self": "/actionwords/1"
}
}
}
This endpoint updates the name, descrpition and/or definition of a single action word of a given project.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the action word from |
| actionword_id | The ID of the action word you want to update |
Delete an action word
DELETE https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
This endpoint delete an action word.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the action word from |
| actionword_id | The ID of the action word you want to delete |
Get an action word callers
GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>/callers HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "scenarios",
"id": "1",
"attributes": {
"created-at": "2018-08-31T09:12:18.338Z",
"updated-at": "2018-08-31T09:12:18.338Z",
"last-author": "harry@example.org",
"name": "It is possible to take 40 coffees before there is really no more beans",
"description": "...",
"folder-id": 1,
"definition": "..."
},
"links": {
"self": "/scenarios/503"
},
"relationships": {
"folder": {},
"tags": {}
}
},
{
"type": "folders",
"id": "1",
"attributes": {
"created-at": "2018-08-31T09:12:17.797Z",
"updated-at": "2018-09-03T14:19:57.066Z",
"last-author": "harry@example.org",
"name": "Serve coffee",
"description": "...",
"definition": "...",
"parent-id": 0
},
"links": {
"self": "/folders/263"
},
"relationships": {
"tags": {}
}
}
]
}
This endpoint retrieves the list of action word callers (scenarios, folders, actionwords).
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the actionword from |
| actionword_id | The ID of the action word you want to get |
Scenarios
Get scenarios of a given project
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios[?include=<fields>] HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "scenarios",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"folder-id": 162629,
"definition": "scenario 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n"
},
"links": {
"self": "/scenarios/1"
},
"relationships": {
"folder": {},
"tags": {},
"actionwords": {},
"test-snapshots": {}
}
},
{
"type": "scenarios",
"id": "2",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Defeat Voldemort",
"description": "And save the world, hurray !",
"folder-id": 162629,
"definition": "scenario 'Defeat Voldemort' do\nend\n"
},
"links": {
"self": "/scenarios/2"
},
"relationships": {
"folder": {},
"tags": {},
"actionwords": {},
"test-snapshots": {}
}
}
]
}
This endpoint retrieves all scenarios of a given project.
You can use the JSONAPI include syntax to fetch additional data about your tests.
The available additional data are the following:
| Field name | Description |
|---|---|
| folder | The folder scenarios belongs to |
| tags | The tags of the scenarios |
| actionwords | Actionwords used by the scenarios |
| test-snapshots | All linked test-snapshots in test runs including their last test results |
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenarios from |
Find scenarios by tags
Find scenarios by tags key
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/find_by_tags?key=<tag_key> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "scenarios",
"id": "1",
"attributes": {
"created-at" : "2018-01-31T16:03:45.387Z",
"updated-at" : "2018-02-05T14:54:50.826Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"folder-id": 162629,
"definition": "scenario 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n"
},
"links": {
"self": "/scenarios/1"
},
"relationships": {
"folder": {}
}
},
{
"type": "scenarios",
"id": "2",
"attributes": {
"created-at" : "2018-02-05T13:15:13.285Z",
"updated-at" : "2018-02-05T13:18:19.397Z",
"last-author" : "harry@example.org",
"name": "Defeat Voldemort",
"description": "And save the world, hurray !",
"folder-id": 162629,
"definition": "scenario 'Defeat Voldemort' do\nend\n"
},
"links": {
"self": "/scenarios/2"
},
"relationships": {
"folder": {}
}
}
],
"included": []
}
Find scenarios by tags key and value
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/find_by_tags?key=<tag_key>&value=<tag_value> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "scenarios",
"id": "1",
"attributes": {
"created-at" : "2018-01-31T16:03:45.387Z",
"updated-at" : "2018-02-05T14:54:50.826Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"folder-id": 162629,
"definition": "scenario 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n"
},
"links": {
"self": "/scenarios/1"
},
"relationships": {
"folder": {}
}
}
],
"included": []
}
This endpoint retrieves all scenarios of a given project and having the given tag.
| Field name | Description |
|---|---|
| tag_key | The KEY of the tag you use to retrieve the scenarios |
| tag_value | The VALUE of the tag you use to retrieve the scenarios |
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenarios from |
Request parameters
| Parameter | Description |
|---|---|
| key | The key of the tag |
| value | The value of the tag |
Get a single scenario
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>[?include=<fields>] HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "scenarios",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"folder-id": 162629,
"definition": "scenario 'Find horcruxes' do\n step {action: \"Find the last one\"}\n step {result: \"Found it!\"}\nend\n",
"errors": []
},
"links": {
"self": "/scenarios/1"
},
"relationships": {
"folder": {}
}
}
}
This endpoint retrieves a single scenario of a given project.
You can use the JSONAPI include syntax to fetch additional data about your tests.
The available additional data are the following:
| Field name | Description |
|---|---|
| folder | The folder the scenario belongs to |
| tags | The tags of the scenario |
| actionwords | Actionwords used by the scenario |
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenario from |
| scenario_id | The ID of the scenario you want to get |
Create a scenario
POST https://studio.cucumber.io/api/projects/<project_id>/scenarios HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "Find horcruxes",
"folder-id": 1234
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data":
{
"type": "scenarios",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"description": "",
"folder-id": "1234",
"definition": "",
"errors": []
},
"links": {
"self": "/scenarios/1"
},
"relationships": {
"folder": {}
}
}
}
This endpoint create a new scenario.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project in which you want to create the scenario |
Mandatory fields
| Field | Description |
|---|---|
| name | (String) The name of the scenario |
Other fields
| Field | Description |
|---|---|
| folder-id | (Integer) The id of the folder containing the scenario |
Update a scenario
PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "scenarios",
"id": <scenario_id>,
"attributes": {
"name": "The new name of the scenario",
"description": "The new description of the scenario",
"definition": "scenario 'The new definition of the scenario' do\nend\n",
"folder-id": "162630"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "scenarios",
"id": "1",
"attributes": {
"name": "The new definition of the scenario",
"description": "The new description of the scenario",
"folder-id": "162630",
"definition": "scenario 'The new definition of the scenario' do\nend\n"
},
"links": {
"self": "/scenarios/1"
},
"relationships": {
"folder": {}
}
}
}
This endpoint updates the name, descrpition, folder and definition of a single scenario of a given project. Note that the attributes are all optional, you can update only one of them if wanted, just don't set the key in the "attributes" hash.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenario from |
| scenario_id | The ID of the scenario you want to update |
Delete a scenario
DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
This endpoint delete a scenario.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenario from |
| scenario_id | The ID of the scenario you want to delete |
List attachments of a given scenario
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/scenarios/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
]
}
This endpoint list all the attachments of a given scenario
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenarios from |
| scenario_id | The ID of the target scenario |
Get a given attachment of a given scenario
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
This endpoint return the requested attachment of a given scenario
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenarios from |
| scenario_id | The ID of the target scenario |
| attachment_id | The ID of the target attachment |
Create an attachment to a given scenario
POST https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"
(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/scenarios/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
}
This endpoint create an attachment to a given scenario
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenarios from |
| scenario_id | The ID of the target scenario |
Update an attachment to a given scenario
PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"
(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/scenarios/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
}
This endpoint update the attachment to a given scenario
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenarios from |
| scenario_id | The ID of the target scenario |
| attachment_id | The ID of the target attachment |
Delete an attachment to a given scenario
DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
This endpoint delete a given attachment of a given scenario
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenarios from |
| scenario_id | The ID of the target scenario |
| attachment_id | The ID of the target attachment |
Features
Get feature from a given folder
GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/feature HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "folders",
"id": "1",
"attributes": {
"created-at": "2018-05-22T09:15:01.430Z",
"updated-at": "2018-10-08T14:42:00.688Z",
"last-author": "harry@example.org",
"name": "HP Saga",
"description": "This project is designed to keep track of the evolution of the HP saga,
in the most expressive way possible, thanks to BDD!",
"definition": "folder do\nend\n",
"parent-id": null,
"feature": "Feature: The Philosopher's Stone\n\nScenario: Read a Hogwarts letter"
},
"links": {
"self": "/folders/1"
},
"relationships": {
"tags": {}
}
},
"included": []
}
This endpoint retrieves Gherkin formatted feature from a specific folder.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the folder you want to get |
Create from feature
POST https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/create_from_feature HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"feature": "Feature: The Chamber of Secrets\n\nScenario: Shopping on Diagon Alley"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "folders",
"id": "2",
"attributes": {
"created-at": "2018-05-22T09:15:01.430Z",
"updated-at": "2018-10-08T14:42:00.688Z",
"last-author": "harry@example.org",
"name": "HP Saga",
"description": "",
"definition": "folder do\nend\n",
"parent-id": null,
"running-feature-imports": [
"the_chamber_of_secrets"
]
},
"links": {
"self": "/folders/2"
},
"relationships": {
"tags": {}
}
},
"included": []
}
This endpoint creates every resources from the feature into a specific folder.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the folder you want to get |
Mandatory fields
| Field | Description |
|---|---|
| feature | (String) The Gherkin formatted feature text |
Update from feature
PATCH https://your_cucumberstudio_url/api/projects/<project_id>/folders/<folder_id>/update_from_feature HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"feature": "Feature: The Chamber of Secrets\n\nScenario: Shopping on Diagon Alley\n\nScenario: ignore Dobby"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type":"folders",
"id":"2",
"attributes":{
"created-at":"2018-05-22T09:15:01.430Z",
"updated-at":"2018-10-08T14:42:00.688Z",
"last-author": "harry@example.org",
"name": "HP Saga",
"description": "This project is designed to keep track of the evolution of the HP saga,
in the most expressive way possible, thanks to BDD!",
"definition":"folder do\nend\n",
"parent-id":1,
"running-feature-imports":["the_chamber_of_secrets"],
"scenarios-count": 1,
"feature-updated-at":"2018-10-08T14:42:00.688Z"
},
"links":{
"self":"/folders/2"
},
"relationships":{
"tags":{}
}
},
"included":[]
}
This endpoint update a folder and its scenarios with the content of a feature file written in Gherkin
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project containing the folder you want to update |
| folder_id | The ID of the folder you want to update |
Mandatory fields
| Field | Description |
|---|---|
| feature | (String) The Gherkin formatted feature text |
Folders
Get folders of a given project
GET https://studio.cucumber.io/api/projects/<project_id>/folders HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "folders",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "HP Saga",
"description": "This project is designed to keep track of the evolution of the HP saga,
in the most expressive way possible, thanks to BDD!",
"parent-id": null
},
"links": {
"self": "/folders/1"
}
},
{
"type": "folders",
"id": "2",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "The Philosopher's Stone",
"description": "",
"parent-id": 1
},
"links": {
"self": "/folders/2"
}
}
]
}
This endpoint retrieves all folders of a given project.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
Find folders by tags
Find folders by tag key
GET https://studio.cucumber.io/api/projects/<project_id>/folders/find_by_tags?key=<tag_key> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "folders",
"id": "791625",
"attributes": {
"created-at": "2019-01-20T22:29:45.135Z",
"updated-at": "2020-07-29T14:34:20.739Z",
"last-author": "harry@example.org",
"name": "Support internationalisation",
"description": "As a polyglot coffee lover\nI can select the language on the coffee machine\nSo I can practice my use of greetings in several languages",
"definition": "folder do\nend\n",
"parent-id": 791623,
"scenarios-count": 0,
"feature-updated-at": "2020-07-29T14:34:20.739Z"
},
"links": {
"self": "/folders/791625"
},
"relationships": {
"tags": {}
}
},
{
"type": "folders",
"id": "791626",
"attributes": {
"created-at": "2019-01-20T22:29:45.190Z",
"updated-at": "2020-07-29T14:34:20.549Z",
"last-author": "harry@example.org",
"name": "Can be configured",
"description": "**In order to** get the best possible coffees\n**As a** geeky coffee lover\n**I can** configure it to match my needs\n",
"definition": "folder do\nend\n",
"parent-id": 791623,
"scenarios-count": 0,
"feature-updated-at": "2020-07-29T14:34:20.549Z"
},
"links": {
"self": "/folders/791626"
},
"relationships": {
"tags": {}
}
}
],
"included": []
}
Find folders by tag key and value
GET https://studio.cucumber.io/api/projects/<project_id>/folders/find_by_tags?key=<tag_key>&value=<tag_value> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "folders",
"id": "1245135",
"attributes": {
"created-at": "2020-02-11T10:42:19.094Z",
"updated-at": "2020-07-29T14:34:20.663Z",
"last-author": "harry@example.org",
"name": "Serve coffee",
"description": "As a coffee lover\nI can get coffee from the machine\nSo I can enjoy the rest of the day",
"definition": "folder do\nend\n",
"parent-id": 791623,
"scenarios-count": 1,
"feature-updated-at": "2020-07-29T14:34:20.663Z"
},
"links": {
"self": "/folders/1245135"
},
"relationships": {
"tags": {}
}
}
],
"included": []
}
This endpoint retrieves all folders of a given project and having the given tag.
| Field name | Description |
|---|---|
| tag_key | The KEY of the tag you use to retrieve the folders |
| tag_value | The VALUE of the tag you use to retrieve the folders |
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
Request parameters
| Parameter | Description |
|---|---|
| key | The key of the tag |
| value | The value of the tag |
Get a single folder
GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "folders",
"id": "2",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "The Philosopher's Stone",
"description": "",
"parent-id": 1
},
"links": {
"self": "/folders/2"
}
}
}
This endpoint retrieves a specific folder of a given project.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the folder you want to get |
Get children of a folder
GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/children HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "folders",
"id": "2",
"attributes": {
"name": "The Philosopher's stone",
"description": "",
"parent-id": 1
},
"links": {
"self": "/folders/2"
}
},
{
"type": "folders",
"id": "3",
"attributes": {
"name": "The Chamber of Secrets",
"description": "",
"parent-id": 1
},
"links": {
"self": "/folders/3"
}
}
]
}
This endpoint retrieves the subfolders of a specific folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the folder you want to get the children |
Get scenarios of a folder
GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/scenarios HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "scenarios",
"id": "1",
"attributes": {
"name": "Read a Hogwarts letter"
},
"links": {
"self": "/scenarios/1"
}
},
{
"type": "scenarios",
"id": "2",
"attributes": {
"name": "Shopping on Diagon Alley"
},
"links": {
"self": "/scenarios/2"
}
}
]
}
This endpoint retrieves the scenarios of a specific folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the folder you want to get the scenarios |
Create a folder
POST https://studio.cucumber.io/api/projects/<project_id>/folders HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "A new folder",
"parent-id": 1234
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"type": "folders",
"id": "1235",
"attributes": {
"created-at": "2017-10-17T08:00:33.978Z",
"updated-at": "2017-10-18T08:28:07.791Z",
"last-author": "harry@example.org",
"name": "A new folder",
"description": "",
"definition": "folder do\nend\n",
"parent-id": 1234
},
"links": {
"self": "/folders/1235"
}
}
}
This endpoint create a new folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
Mandatory fields
| Field | Description |
|---|---|
| name | (String) The name of the folder. |
Other fields
| Field | Description |
|---|---|
| parent-id | (Integer) The id of the folder that will contain the created folder. |
Update a folder
PATCH https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "folders",
"id": "<folder_id>",
"attributes": {
"name": "A new folder name",
"description": "A new description",
"definition": "folder do end"
"parent-id": 1233
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "folders",
"id": "1234",
"attributes": {
"created-at": "2017-10-17T08:00:33.978Z",
"updated-at": "2017-10-18T08:28:07.791Z",
"last-author": "harry@example.org",
"name": "A new folder name",
"description": "A new descriptio",
"definition": "folder do\nend\n",
"parent-id": 1233
},
"links": {
"self": "/folders/1234"
}
}
}
This endpoint updates a folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
Fields
| Field | Description |
|---|---|
| name | (String) The name of the folder. |
| description | (String) The description of the folder. |
| definition | (String) The definition of the folder. |
| parent-id | (Integer) The id of the parent folder. |
Delete a folder
DELETE https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {}
}
This endpoint destroy a folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the target folder |
Delete a folder children
DELETE https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/children HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {}
}
This endpoint destroys all sub-folders of the target folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the target folder |
Delete a folder scenarios
DELETE https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/scenarios HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {}
}
This endpoint destroy a folder scenarios
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the target folder |
List attachments of a given folder
GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/folders/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
]
}
This endpoint list all the attachments of a given folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the target folder |
Get a given attachment of a given folder
GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
This endpoint return the requested attachment of a given folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the target folder |
| attachment_id | The ID of the target attachment |
Create an attachment to a given folder
POST https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"
(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/folders/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
}
This endpoint create an attachment to a given folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the target folder |
Update an attachment to a given folder
PATCH https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"
(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/folders/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
}
This endpoint update the attachment to a given folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the target folder |
| attachment_id | The ID of the target attachment |
Delete an attachment to a given folder
DELETE https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
This endpoint delete a given attachment of a given folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| folder_id | The ID of the target folder |
| attachment_id | The ID of the target attachment |
Tags
Include tags when requesting elements
GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>?include=tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "folders",
"id": "2",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "The Philosopher's Stone",
"description": "",
"parent-id": 1
},
"links": {
"self": "/folders/2"
},
"relationships": {
"tags": {
"data": [
{
"type": "tags",
"id": "6537"
}
]
}
}
},
"included": [
{
"type": "tags",
"id": "6539",
"attributes": {
"key": "horcruxes",
"value": ""
},
"links": {
"self": "/tags/6539"
}
}
]
}
You can use the JSONAPI include syntax to fetch tags alongside parent elements. Elements can be scenarios, actionwords, folders, test runs, tests and test folders. This is working when requesting for a list of elements, and for a single element.
Get tags of a given action word
GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "1",
"attributes": {
"key": "platform",
"value": "Android"
},
"links": {
"self": "/tags/1"
}
},
{
"type": "tags",
"id": "2",
"attributes": {
"key": "automated",
"value": "yes"
},
"links": {
"self": "/tags/2"
}
}
]
}
This endpoint retrieves all tags of a given action word.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted action word |
| actionword_id | The ID of the action word you want to retrieve the tags from |
Get tags of a given scenario
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "1",
"attributes": {
"key": "Status",
"value": "InProgress"
},
"links": {
"self": "/tags/1"
}
},
{
"type": "tags",
"id": "2",
"attributes": {
"key": "Priority",
"value": "Over9000"
},
"links": {
"self": "/tags/2"
}
}
]
}
This endpoint retrieves all tags of a given scenario.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the tags from |
Get tags of a given folder
GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "1",
"attributes": {
"key": "Javascript",
"value": ""
},
"links": {
"self": "/tags/1"
}
},
{
"type": "tags",
"id": "2",
"attributes": {
"key": "Sprint",
"value": "1"
},
"links": {
"self": "/tags/2"
}
}
]
}
This endpoint retrieves all tags of a given folder.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted folder |
| folder_id | The ID of the folder you want to retrieve the tags from |
Get tags of a given test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "1",
"attributes": {
"key": "priority",
"value": "high"
},
"links": {
"self": "/tags/1"
}
},
{
"type": "tags",
"id": "2",
"attributes": {
"key": "jira",
"value": "test"
},
"links": {
"self": "/tags/2"
}
}
]
}
This endpoint retrieves all tags of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted test run |
| test_run_id | The ID of the test run you want to retrieve the tags from |
Get tags of a given test
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "1",
"attributes": {
"key": "priority",
"value": "high"
},
"links": {
"self": "/tags/1"
}
},
{
"type": "tags",
"id": "2",
"attributes": {
"key": "jira",
"value": "test"
},
"links": {
"self": "/tags/2"
}
}
]
}
This endpoint retrieves all tags of a given test.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted test run |
| test_run_id | The ID of the test run where the test is |
| test_snapshot_id | The ID of the test in the test-run you want to retrieve the tags from |
Create tag in a scenario
POST https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"key": "priority",
"value": "high"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "1",
"attributes": {
"key": "priority",
"value": "high"
},
"links": {
"self": "/tags/1"
}
}
]
}
This endpoint creates a new tag in a scenario.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario where you want to create the tag |
Create tag in a test run
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"key": "priority",
"value": "high"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "1",
"attributes": {
"key": "priority",
"value": "high"
},
"links": {
"self": "/tags/1"
}
}
]
}
This endpoint creates a new tag in a test run.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted test run |
| test_run_id | The ID of the test run where you want to create the tag |
Create tag in a test
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"key": "priority",
"value": "high"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "1",
"attributes": {
"key": "priority",
"value": "high"
},
"links": {
"self": "/tags/1"
}
}
]
}
This endpoint creates a new tag in a test.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted test run |
| test_run_id | The ID of the test run where the test is |
| test_snapshot_id | The ID of the test in the test-run where you want to create the tag |
Update a tag in a scenario
PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags/<tag_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "tags",
"id": 5,
"attributes": {
"key": "priority",
"value": "low"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "5",
"attributes": {
"key": "priority",
"value": "low"
},
"links": {
"self": "/tags/1"
}
}
]
}
This endpoint updates a tag in a scenario.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario where you want to update the tag |
| tag_id | The ID of the tag you want to update |
Update a tag in a test run
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags/<tag_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "tags",
"id": 5,
"attributes": {
"key": "priority",
"value": "low"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "5",
"attributes": {
"key": "priority",
"value": "low"
},
"links": {
"self": "/tags/1"
}
}
]
}
This endpoint updates a tag in a test run.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted test run |
| test_run_id | The ID of the test run where you want to update the tag |
| tag_id | The ID of the tag you want to update |
Update a tag in a test
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags/<tag_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "tags",
"id": 5,
"attributes": {
"key": "priority",
"value": "low"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "tags",
"id": "5",
"attributes": {
"key": "priority",
"value": "low"
},
"links": {
"self": "/tags/1"
}
}
]
}
This endpoint updates a tag in a test run.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted test run |
| test_run_id | The ID of the test run where the test is |
| test_snapshot_id | The ID of the test you want to update the tag |
| tag_id | The ID of the tag you want to update |
Delete a tag in a scenario
DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags/<tag_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
This endpoint deletes a tag in a scenario.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario where you want to delete the tag |
| tag_id | The ID of the tag you want to delete |
Delete a tag in a test run
DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags/<tag_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
This endpoint deletes a tag in a test run.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted test run |
| test_run_id | The ID of the test run where you want to delete the tag |
| tag_id | The ID of the tag you want to delete |
Delete a tag in a test
DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags/<tag_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
This endpoint deletes a tag in a test run.
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted test run |
| test_run_id | The ID of the test run where the test is |
| test_snapshot_id | The ID of the test where you want to delete the tag |
| tag_id | The ID of the tag you want to delete |
Create tags alongside elements
POST https://studio.cucumber.io/api/projects/<project_id>/<element_type> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
...
},
"relationships": {
"tags": {
"data": [
{ "type": "tag", "key": "automated" },
{ "type": "tag", "key": "sprint", value: "2" },
{ "type": "tag", "key": "priority", value: "high" }
]
}
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data":
{
"type": "test-runs",
"id": "1",
"attributes": {
...
},
"links": {
"self": "/test-runs/1"
},
"included": [
{ "type": "tags", "id": "1", "attributes": { "key": "automated", "value": "" }, "links": { "self": "/tags/1" } },
{ "type": "tags", "id": "2", "attributes": { "key": "sprint", "value": "2" }, "links": { "self": "/tags/2" } },
{ "type": "tags", "id": "3", "attributes": { "key": "priority", "value": "high" }, "links": { "self": "/tags/3" } }
]
}
}
With some elements (such as the test runs and scenarios), you can create one or multiple tags linked to the created element. This can be done by specifying the "relationships" element.
| Parameter | Description |
|---|---|
| project_id | The ID of the project in wich you want to create the actionword |
| element_type | The type of element you want to create (scenarios, test_runs) |
Datasets
Get datasets of a given scenario
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "datasets",
"id": "1",
"attributes": {
"name": "dataset-1",
"data": {
"parameter-1": "value 1-1",
"parameter-2": "value 1-2"
}
},
"links": {
"self": "/datasets/1"
}
},
{
"type": "datasets",
"id": "2",
"attributes": {
"name": "dataset-2",
"data": {
"parameter-1": "value 2-1",
"parameter-2": "value 2-2"
}
},
"links": {
"self": "/datasets/2"
}
}
]
}
This endpoint retrieves all datasets of a given scenario.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the datasets from |
Get a given dataset
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "datasets",
"id": "1",
"attributes": {
"name": "dataset-1",
"data": {
"parameter-1": "value 1-1",
"parameter-2": "value 1-2"
}
},
"links": {
"self": "/datasets/1"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the datasets from |
| dataset_id | The ID of the dataset you want to show |
Create a dataset
POST https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "dataset-3",
"data": {
"parameter-1": "value 3-1",
"parameter-2": "value 3-2"
}
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"type": "datasets",
"id": "3",
"attributes": {
"name": "dataset-3",
"data": {
"parameter-1": "value 3-1",
"parameter-2": "value 3-2"
}
},
"links": {
"self": "/datasets/3"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the datasets from |
Update a dataset
PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "datasets",
"id": "3",
"attributes": {
"name": "new dataset-3 name",
"data": {
"parameter-1": "new value 3-1",
"parameter-2": "new value 3-2"
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "datasets",
"id": "3",
"attributes": {
"name": "new dataset-3 name",
"data": {
"parameter-1": "new value 3-1",
"parameter-2": "new value 3-2"
}
},
"links": {
"self": "/datasets/3"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the datasets from |
| dataset_id | The ID of the dataset you want to update |
Delete a dataset
DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the datasets from |
| dataset_id | The ID of the dataset you want to destroy |
Datatables
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datatable HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "datasets",
"id": "1",
"attributes": {
"name": "dataset-1",
"data": {
"parameter-1": "value 1-1",
"parameter-2": "value 1-2"
}
},
"links": {
"self": "/datasets/1"
}
},
{
"type": "datasets",
"id": "2",
"attributes": {
"name": "dataset-2",
"data": {
"parameter-1": "value 2-1",
"parameter-2": "value 2-2"
}
},
"links": {
"self": "/datasets/2"
}
}
]
}
A datatable endpoint is available as an alias for the datasets
resource.
Parameters
Get parameters of a given scenario
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "parameters",
"id": "1",
"attributes": {
"name": "parameter-1"
},
"links": {
"self": "/parameters/1"
}
},
{
"type": "parameters",
"id": "2",
"attributes": {
"name": "parameter-2"
},
"links": {
"self": "/parameters/2"
}
}
]
}
This endpoint retrieves all parameters of a given scenario.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the parameters from |
Get a given parameter
GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "parameters",
"id": "1",
"attributes": {
"name": "parameter-1"
},
"links": {
"self": "/parameters/1"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the parameters from |
| parameter_id | The ID of the parameter you want to show |
Create a parameter
POST https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "parameter-3"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"type": "parameters",
"id": "3",
"attributes": {
"name": "parameter-3"
},
"links": {
"self": "/parameters/3"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the parameters from |
Update a parameter
PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "parameters",
"id": "3",
"attributes": {
"name": "new parameter-3 name"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "parameters",
"id": "3",
"attributes": {
"name": "new_parameter-3_name"
},
"links": {
"self": "/parameters/3"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the parameters from |
| parameter_id | The ID of the parameter you want to update |
Delete a parameter
DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the wanted scenario |
| scenario_id | The ID of the scenario you want to retrieve the parameters from |
| parameter_id | The ID of the parameter you want to destroy |
Test runs
Get test runs of a project
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "test-runs",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Sprint 1",
"description": "Wandering in the countryside, doing boring stuff",
"statuses": {
"passed": 0,
"failed": 0,
"retest": 0,
"undefined": 765,
"blocked": 0,
"skipped": 0,
"wip": 0
},
"archived": false,
"external": false
},
"links": {
"self": "/test-runs/1"
},
"relationships": {
"tags": {}
}
},
{
"type": "test-runs",
"id": "2",
"attributes": {
"name": "Sprint 2",
"description": "Bank robbery and blowing up things",
"statuses": {
"passed": 15,
"failed": 42,
"retest": 0,
"undefined": 0,
"blocked": 0,
"skipped": 0,
"wip": 0
},
"archived": true,
"external": false
},
"links": {
"self": "/test-runs/2"
},
"relationships": {
"tags": {}
}
}
]
}
This endpoint retrieves all test runs of a given project. The order is undefined.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test runs from |
| filter[status] | "active" or "archived" |
Get a single test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "test-runs",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Sprint 1",
"description": "Wandering in the countryside, doing boring stuff",
"statuses": {
"passed": 0,
"failed": 0,
"retest": 0,
"undefined": 765,
"blocked": 0,
"skipped": 0,
"wip": 0
},
"archived": false,
"external": false
},
"links": {
"self": "/test-runs/1"
},
"relationships": {
"tags": {}
}
}
}
This endpoint retrieves a single test run of a given project.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test run from |
| test_run_id | The ID of the test run you want to get |
Archive test runs
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/archive?older_than=2021-02-13 HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"meta": {
"archived_test_run_ids": [12, 15]
}
}
This endpoint archives all test runs older than the specified date.
URL Parameters
| Parameter | Description |
|---|---|
| older_than | An ISO 8601 date (YYYY-MM-DD). All test runs created before this date will be archived. Mandatory. |
Include tags when fetching your test run(s)
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs?include=tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Also works when retrieving a single test run
You can use the JSONAPI include syntax to fetch the tags of your test runs
Create a test run
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "Sprint 1",
"description": "My TR description",
"scenario_ids": [1, 2, 3]
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data":
{
"type": "test-runs",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Sprint 1",
"description": "My TR description",
"statuses": {
"passed": 0,
"failed": 0,
"retest": 0,
"undefined": 3,
"blocked": 0,
"skipped": 0,
"wip": 0
},
"archived": false,
"external": false
},
"links": {
"self": "/test-runs/1"
},
"relationships": {
"tags": {}
}
}
}
This endpoint creates a new test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project in which you want to create the test run. |
Mandatory fields
| Field | Description |
|---|---|
| name | (String) The name of the test run. |
Other fields
| Field | Description |
|---|---|
| scenario_ids | (List of Integer) The ids of scenarios you want in the test run. |
| external | 1 or true to create an external test run. |
| description | (String) The description of the test run. |
Update test run description
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test_runs",
"id": <test_run_id>,
"attributes": {
"description": "My new test run description"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data":
{
"type": "test-runs",
"id": "3",
"attributes": {
"created-at": "2021-06-10T09:35:01.975Z",
"updated-at": "2021-06-14T12:19:32.607Z",
"last-author" : "harry@example.org",
"name": "My new test run",
"description": "My new test run description",
"statuses": {},
"archived": false,
"external": false
},
"links": {
"self": "/test-runs/3"
},
"relationships": {
"tags": {}
}
}
}
This endpoint updates the description of a given test run.
Clone a test run
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "My new test run",
"test_run_id": 1
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data":
{
"type": "test-runs",
"id": "2",
"attributes": {
"created-at": "2019-05-23T08:30:17.398Z",
"updated-at": "2019-05-23T08:30:17.398Z",
"last-author" : "harry@example.org",
"name": "My new test run",
"description": "first test run description",
"statuses": {},
"archived": false,
"external": false
},
"links": {
"self": "/test-runs/2"
},
"relationships": {
"tags": {}
}
}
}
This endpoint clones a test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project in which you want to create the test run. |
Mandatory fields
| Field | Description |
|---|---|
| name | (String) The name of the test run. |
| test_run_id | (Integer) The id of the source test run. |
Synchronize a test run
Synchronization give you the ability to update the tests of your test run with their last version, based on the current scenarios definitions
Watch synchronization state
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>?show_synchronization_information=true HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "test-runs",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Sprint 1",
"description": "Wandering in the countryside, doing boring stuff",
"statuses": {
"passed": 0,
"failed": 0,
"retest": 0,
"undefined": 765,
"blocked": 0,
"skipped": 0,
"wip": 0
},
"archived": false,
"external": false,
"synchronization-information": {
"synchronizable": true,
"synchronizing": false,
"details": {
"deleted_folders_snapshots": [],
"deleted_scenarios_snapshots": [],
"deleted_tests_snapshots": []
}
}
},
"links": {
"self": "/test-runs/1"
},
"relationships": {
"tags": {}
}
}
}
This endpoint is useful to track the state of a test run synchronization.
The synchronization operation can be dangerous. If some of your test run tests and folders are based on scenarios and folders that no longer exist, they will be destroyed. It is strongly advised to use this endpoint to get the potential impacts of a synchronization before running one.
Synchronize the test run
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/synchronize HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "test-runs",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Sprint 1",
"description": "Wandering in the countryside, doing boring stuff",
"statuses": {
"passed": 0,
"failed": 0,
"retest": 0,
"undefined": 765,
"blocked": 0,
"skipped": 0,
"wip": 0
},
"archived": false,
"external": false,
"synchronization-information": {
"synchronizable": true,
"synchronizing": true,
"details": {
"deleted_folders_snapshots": [],
"deleted_scenarios_snapshots": [],
"deleted_tests_snapshots": []
}
}
},
"links": {
"self": "/test-runs/1"
},
"relationships": {
"tags": {}
}
}
}
This endpoint will start the synchronization of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project containing the test run |
| test_run_id | The ID of the test run you want to synchronize |
Get builds history of a test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/build_history HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": 3,
"date": "2018-09-12T08:19:28.446Z",
"values": {
"passed": 1,
"failed": 1,
"wip": 0,
"retest": 1,
"blocked": 0,
"skipped": 0,
"undefined": 0
},
"platform": "Default"
},
{
"id": 2,
"date": "2018-09-12T08:19:09.615Z",
"values": {
"passed": 2,
"failed": 0,
"wip": 1,
"retest": 0,
"blocked": 0,
"skipped": 0,
"undefined": 0
},
"platform": "Default"
},
{
"id": 1,
"date": "2018-09-12T07:21:21.606Z",
"values": {
"passed": 2,
"failed": 1,
"wip": 0,
"retest": 0,
"blocked": 0,
"skipped": 0,
"undefined": 0
},
"platform": "Default"
}
]
}
This endpoint retrieves build history of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test run from |
| test_run_id | The ID of the test run you want to get |
Add a scenario to an existing test run
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test_runs",
"id": 1,
"attributes": {
"scenario_id": 1
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "test-runs",
"id": "1",
"attributes": {
"created-at" : "2019-05-27T11:39:08.281Z",
"updated-at" : "2019-05-27T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Sprint 1",
"description": "Wandering in the countryside, doing boring stuff",
"statuses": {
"passed": 0,
"failed": 0,
"retest": 0,
"undefined": 765,
"blocked": 0,
"skipped": 0,
"wip": 0
},
"archived": false,
"external": false
},
"links": {
"self": "/test-runs/1"
},
"relationships": {
"tags": {}
}
}
]
}
This endpoint adds a scenario to a given test run.
Add multiple scenarios to an existing test run
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test_runs",
"id": 1,
"attributes": {
"scenario_ids": [2233,76547]
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "test-runs",
"id": "1",
"attributes": {
"created-at" : "2019-05-27T11:39:08.281Z",
"updated-at" : "2019-05-27T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Sprint 1",
"description": "Wandering in the countryside, doing boring stuff",
"statuses": {
"passed": 0,
"failed": 0,
"retest": 0,
"undefined": 767,
"blocked": 0,
"skipped": 0,
"wip": 0
},
"archived": false,
"external": false
},
"links": {
"self": "/test-runs/1"
},
"relationships": {
"tags": {}
}
}
]
}
This endpoint adds several scenarios to a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test run from |
| test_run_id | The ID of the test run you want to get |
List attachments of a given test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/test_runs/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
]
}
This endpoint list all the attachments of a given test run
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test run from |
| test_run_id | The ID of the target test run |
Get a given attachment of a given test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
This endpoint return the requested attachment of a given test run
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test run from |
| test_run_id | The ID of the target test run |
| attachment_id | The ID of the target attachment |
Create an attachment to a given test run
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"
(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/test_runs/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
}
This endpoint create an attachment to a given test run
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test run from |
| test_run_id | The ID of the target test run |
Update an attachment to a given test run
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"
(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/test_runs/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
}
This endpoint update the attachment to a given test run
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test run from |
| test_run_id | The ID of the target test run |
| attachment_id | The ID of the target attachment |
Delete an attachment to a given test run
DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
This endpoint delete a given attachment of a test run
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test run from |
| test_run_id | The ID of the target test run |
| attachment_id | The ID of the target attachment |
Tests
Get tests of a test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "test-snapshots",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"definition-json": {
"scenario_name": "Find horcruxes",
"dataset_name": null,
"dataset_id": null,
"steps": [
{
"action": "Given Harry has one horcrux"
},
{
"result": "Then he should destroy it"
},
],
"index": 0
},
"status": "failed",
"scenario-snapshot-id": 1,
"folder-snapshot-id": 2
},
"links": {
"self": "/test-snapshots/1"
},
"relationships": {
"scenario": {},
"dataset": {},
"last-result": {}
}
},
{
"type": "test-snapshots",
"id": "2",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Defeat Voldemort",
"definition-json": {
"scenario_name": "Defeat Voldemort",
"dataset_name": null,
"dataset_id": null,
"steps": [
{
"action": "Given Harry cast the Expelliarmus spell"
},
{
"result": "Then Voldemort should be defeated"
}
],
"index": 0
},
"status": "success",
"scenario-snapshot-id": 1,
"folder-snapshot-id": 5
},
"links": {
"self": "/test-snapshots/2"
},
"relationships": {
"scenario": {},
"dataset": {},
"last-result": {}
}
}
]
}
This endpoint retrieves all test snapshots of a test run
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the tests from |
| test_run_id | The ID of the test run that contains the tests you want |
Optional parameter
| Parameter | Description |
|---|---|
| show_step_statuses (value: 'true') | Embed detailed test results including statuses per step with every tests |
Errors
If the test run has just been created and the tests generation is still in progress, this endpoint will return a HTTP 423 Locked error until the tests generation finishes.
Get a test
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "test-snapshots",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"definition-json": {
"scenario-name": "Find horcruxes",
"dataset_name": null,
"dataset_id": null,
"steps": [
{
"action": "Given Harry has one horcrux"
},
{
"result": "Then he should destroy it"
},
],
"index": 0
},
"status": "failed",
"scenario-snapshot-id": 1,
"folder-snapshot-id": 5
},
"links": {
"self": "/test-snapshots/1"
},
"relationships": {
"scenario": {},
"dataset": {},
"last-result": {}
}
}
}
This endpoint retrieves a particular test of a test run
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the tests from |
| test_run_id | The ID of the test run that contains the test you want |
| test_snapshot_id | The ID of the test you want to get |
Get a test additional data
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>?include=<fields> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
You can use the JSONAPI include syntax to fetch additional data about your tests.
Following example returns a test with scenario, last result and the pass rate.
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>?include=dataset,scenario&show_passrate HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "test-snapshots",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"name": "Find horcruxes",
"definition-json": {
"scenario-name": "Find horcruxes",
"dataset_name": null,
"dataset_id": null,
"steps": [
{
"action": "Given Harry has one horcrux"
},
{
"result": "Then he should destroy it"
},
],
"index": 0
},
"status": "passed",
"scenario-snapshot-id": 1,
"folder-snapshot-id": 5,
"pass-rate": "75"
},
"links": {
"self": "/test-snapshots/1"
},
"relationships": {
"scenario": {
"data": {
"type": "scenarios",
"id": "10"
}
},
"dataset": {},
"last-result": {
"links": {
"self": "/test-snapshots/1/relationships/last-result",
"related": "/test-snapshots/1/last-result"
},
"data": {
"type": "test-results",
"id": "7"
}
}
}
},
"included": [
{
"type": "scenarios",
"id": "10",
"attributes": {
"created-at": "2017-02-26T07:10:42.651Z",
"updated-at": "2017-02-26T10:22:23.206Z",
"last-author": "harry@example.org",
"name": "Find horcruxes",
"description": "That will help to kill Voldemort",
"folder-id": 162629,
"definition": "scenario 'Find horcruxes' do\n call given 'Harry has one horcrux'\n call then 'he should destroy it\nend\n"
},
"links": {
"self": "/scenarios/10"
},
"relationships": {
"folder": {}
}
},
{
"type": "test-results",
"id": "7",
"attributes": {
"created-at": "2017-03-01T14:38:16.612Z",
"updated-at": "2018-03-01T14:38:16.612Z",
"last-author": "harry@example.org",
"status": "passed",
"description": null,
"status-author": "Harry",
"step-statuses": [
"passed",
"passed"
]
},
"links": {
"self": "/test-results/7"
},
"relationships": {
"test-snapshot": {},
"build": {},
"execution-environment": {}
}
}
]
}
The available additional data are the following:
| Field name | Description |
|---|---|
| scenario | The original scenario that produced the test |
| dataset | The dataset that produced the test (if it comes from a scenario using a datatable) |
| last-result | The details of the last test result of the test |
show_passrate parameter can be added to include test pass rate in the response.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the tests from |
| test_run_id | The ID of the test run that contains the test you want |
| test_snapshot_id | The ID of the test you want to get |
Request parameters
| Parameter | Description |
|---|---|
| include | The data to include in the test JSON response. Fields must be comma-separated |
| show_passrate | Add this parameter to get the test pass rate in the data |
Delete a test
DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
This endpoint delete a test.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the tests from |
| test_run_id | The ID of the test run that contains the test you want |
| test_snapshot_id | The ID of the test you want to get |
Test folders
Get test folders of a test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "folder-snapshots",
"id": "1",
"attributes": {
"created-at": "2017-09-15T12:59:08.328Z",
"updated-at": "2017-09-15T12:59:08.710Z",
"last-author": "HarryP",
"name": "A Hogwarts project",
"description": "",
"statuses": {
"passed_count": 0,
"failed_count": 0,
"retest_count": 0,
"undefined_count": 3,
"blocked_count": 0,
"skipped_count": 0,
"wip_count": 0
},
"parent-id": null,
"test-run-id": 1
},
"links": {
"self": "/folder-snapshots/1"
},
"relationships": {
"folder": {},
"children": {},
"test-snapshots": {}
}
},
{
"type": "folder-snapshots",
"id": "1",
"attributes": {
"created-at": "2017-09-15T12:59:08.328Z",
"updated-at": "2017-09-15T12:59:08.710Z",
"last-author": "HarryP",
"name": "The Philosopher's Stone",
"description": "",
"statuses": {
"passed_count": 0,
"failed_count": 0,
"retest_count": 0,
"undefined_count": 3,
"blocked_count": 0,
"skipped_count": 0,
"wip_count": 0
},
"parent-id": 1,
"test-run-id": 1
},
"links": {
"self": "/folder-snapshots/1"
},
"relationships": {
"folder": {},
"children": {},
"test-snapshots": {}
}
}
]
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test folders from |
| test_run_id | The ID of the test run that contains the test folders you want |
Get a test folder
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "folder-snapshots",
"id": "1",
"attributes": {
"created-at": "2017-09-15T12:59:08.328Z",
"updated-at": "2017-09-15T12:59:08.710Z",
"last-author": "HarryP",
"name": "A Hogwarts project",
"description": "",
"statuses": {
"passed_count": 0,
"failed_count": 0,
"retest_count": 0,
"undefined_count": 3,
"blocked_count": 0,
"skipped_count": 0,
"wip_count": 0
},
"parent-id": null,
"test-run-id": 1
},
"links": {
"self": "/folder-snapshots/1"
},
"relationships": {
"folder": {},
"children": {},
"test-snapshots": {}
}
}
]
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test folders from |
| test_run_id | The ID of the test run that contains the test folders you want |
| folder_snapshot_id | The ID of the test folder you want to get |
Get a test folder additional data
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=<fields> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
The data you want to include in the response must be comma-separated
You can use the JSONAPI include syntax to fetch additional data about your tests.
The available additional data are the following:
| Field name | Description |
|---|---|
| folder | The original folder that produced the test folder |
| children | The subfolders of the test folder |
| test-snapshots | The tests contained by the test folder |
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=folder HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Get a test folder original scenario folder
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=children HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Get the subfolders of a test folder
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=test-snapshots HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Get the tests of a test folder
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test folders from |
| test_run_id | The ID of the test run that contains the test folders you want |
| folder_snapshot_id | The ID of the test folder you want to get |
Request parameters
| Parameter | Description |
|---|---|
| include | The data to include in the test JSON response. Fields must be comma-separated |
Test execution
Getting started with test executions
Test execution results in CucumberStudio are organized in the following way:
- Test execution results are grouped into builds
- Each build belongs to an execution environment
- A test run can contain multiple execution environments, each containing their own builds of test execution results.
The notion of execution environments is entirely optional. You can use them if you have several environments on which you want to execute your tests. If you do not wish to have specific environments, you can ignore them and work directly with builds at test run level.
The Builds section specifies all operations that can be performed without execution environments.
The Execution environments section specifies how to work with multiple environments.
Each entry in the Builds section has a warning if an execution environment ID is mandatory when working with multiple environments.
Add a test execution result
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test-results",
"attributes": {
"status": "passed",
"status-author": "Harry",
"description": "All was well",
"step-statuses": ["passed", "passed", "passed"]
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
Newly created test result
{
"data": {
"type": "test-results",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"status": "passed",
"created-at": "Couple of miliseconds ago",
"description": "",
"status-author": "Harry",
"step-statuses": ["passed", "passed", "passed"]
},
"links": {
"self": "/test-results/1"
},
"relationships": {
"test-snapshot": {
"data": {
"type": "test-snapshots",
"id": "1"
}
},
"build": {
"data": null
}
}
},
"included": [
{
"test-snapshot": "test data"
}
]
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the tests from |
| test_run_id | The ID of the test run that contains the test you want |
| test_snapshot_id | The ID of the test whose you want add a test result to |
Mandatory fields
| Field | Description |
|---|---|
| status | (String) The result of the test execution. Possible values are 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', 'undefined'. |
| status-author | (String) The name of the author of the test execution |
| description | (String) A comment about the test execution |
Optional fields
| Field | Description |
|---|---|
| build | (JSONAPI Relationship) The build containing your test execution result |
| execution-environment | (JSONAPI Relationship) The execution environment containing your test execution result |
| step-statuses | (String Array) The status for each individual step |
If a build is provided, the test result will be created into that build.
If an execution environment is provided, the test result will be created into the current build of that execution environment
If step statuses are provided, anything different from 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', or 'undefined' will be interpreted as 'undefined'. If providing something else than a array of statuses, it will be interpreted as empty array, which means all step statuses are 'undefined'.
When setting step statuses on creation, they can match the steps of the scenario, or the steps of the test. The number of steps in each case can be different because a call to an actionword step can expand into multiple steps:. So the following rules apply:
- If the given step statuses array is of the same size or bigger than the number of steps in the test, the given step statuses will be interpreted as test step statuses
- If the given step statuses array is smaller than the number of steps in the test, the given step statuses will be interpreted as scenario step statuses, and will be expanded accordingly to the scenario.
For instance, if a scenario has two steps, and each one is a call to an actionword having 2 steps, then the scenario has 2 steps and the corresponding test has 4 steps. Here are the possibilities:
- Creating a test result with step statuses being
['passed', 'failed']will be interpreted as scenario steps and be expanded to['passed', 'passed', 'failed', 'failed']. - Creating a test result with step statuses being
['passed', 'failed', 'skipped', 'skipped']will be interpreted as test steps and used as-is. - Creating a test result with step statuses being
['passed']will be interpreted as scenario steps and be expanded to['passed', 'passed']. Unspecified statuses are always'undefined'. - Creating a test result with step statuses being
['passed', 'failed', 'skipped']will be interpreted as scenario steps and be expanded to['passed', 'passed', 'failed', 'failed']. The extra'skipped'is dropped. - Creating a test result with step statuses being
['passed', 'failed', 'skipped', 'skipped', 'wip']will be interpreted as test steps and used as-is. The extra'wip'is dropped.
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test-results",
"attributes": {"status": "passed", "status-author": "Harry", "description": "All was well"},
"relationships": {
"build": {
"data": {
"type": "build",
"id": 1
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Newly created test result
{
"data": {
"type": "test-results",
"id": "1",
"attributes": {
"status": "passed",
"created-at": "Couple of miliseconds ago",
"description": "",
"status-author": "Harry"
},
"links": {
"self": "/test-results/1"
},
"relationships": {
"test-snapshot": {
"data": {
"type": "test-snapshots",
"id": "1"
}
},
"build": {
"data": {
"type": "builds",
"id": "1"
}
}
}
},
"included": [
{
"type": "test-snapshots",
"attributes": "test data"
},
{
"type": "builds",
"attributes": "build data"
}
]
}
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test-results",
"attributes": {"status": "passed", "status-author": "Harry", "description": "All was well"},
"relationships": {
"execution-environment": {
"data": {
"type": "execution-environment",
"id": 1
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Newly created test result
{
"data": {
"type": "test-results",
"id": "1",
"attributes": {
"status": "passed",
"created-at": "Couple of miliseconds ago",
"description": "",
"status-author": "Harry"
},
"links": {
"self": "/test-results/1"
},
"relationships": {
"test-snapshot": {
"data": {
"type": "test-snapshots",
"id": "1"
}
},
"build": {
"data": {
"type": "builds",
"id": "1"
}
}
}
},
"included": [
{
"type": "test-snapshots",
"attributes": "test data"
},
{
"type": "builds",
"attributes": "build data"
}
]
}
Update a test execution result
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test-results",
"id": <test_result_id>,
"attributes": {
"status": "passed",
"status-author": "Jenkins",
"description": "Automated jenkins job"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Updated test result
{
"data": {
"type": "test-results",
"id": "<test_result_id>",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"last-author" : "harry@example.org",
"status": "passed",
"created-at": "Couple of miliseconds ago",
"description": "Automated jenkins job",
"status-author": "Jenkins"
},
"links": {
"self": "/test-results/<test_result_id>"
},
"relationships": {
"test-snapshot": {},
"build": {}
}
}
}
The API allows you to update a test result following the {json:api} way to patch resources.
Status, author and/or description may be updated specifying the
status, status-author and/or description attributes of the resource.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the tests from |
| test_run_id | The ID of the test run that contains the test you want |
| test_snapshot_id | The ID of the test whose you want to update a test result to |
| test_result_id | The ID of the test result you want to update |
Attributes that may be updated
| Field | Description |
|---|---|
| status | (String) The status of the test execution. Possible values are 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', 'undefined'. |
| status-author | (String) The name of the author of the test execution |
| description | (String) A comment about the test execution |
List attachments of a given test execution result
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/test_runs/1/test_snapshots/1/test_results/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
]
}
This endpoint list all the attachments of a given test execution result
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test execution result from |
| test_run_id | The ID of the test run you want to retrieve the test execution result from |
| test_snapshot_id | The ID of the test that you want to retrieve the test execution result from |
| test_result_id | The ID of the test execution result you want |
Get a given attachment of a given test execution result
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
This endpoint return the requested attachment of a given test execution result
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test execution result from |
| test_run_id | The ID of the test run you want to retrieve the test execution result from |
| test_snapshot_id | The ID of the test that you want to retrieve the test execution result from |
| test_result_id | The ID of the test execution result you want |
Create an attachment to a given test execution result
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"
(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/test_runs/1/test_snapshots/1/test_results/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
}
This endpoint create an attachment to a given test execution result
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test execution result from |
| test_run_id | The ID of the test run you want to retrieve the test execution result from |
| test_snapshot_id | The ID of the test that you want to retrieve the test execution result from |
| test_result_id | The ID of the test execution result you want |
Update an attachment to a given test run
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"
(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "attachments",
"id": "1",
"attributes": {
"id": 1,
"file-name": "my-attachment.jpg",
"file-url": "/api/projects/1/test_runs/1/test_snapshots/1/test_results/1/attachments/1",
"file-size": 100
},
"links": {
"self": "/attachments/1"
}
}
}
This endpoint update the attachment to a given test execution result
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test execution result from |
| test_run_id | The ID of the test run you want to retrieve the test execution result from |
| test_snapshot_id | The ID of the test that you want to retrieve the test execution result from |
| test_result_id | The ID of the test execution result you want |
| attachment_id | The ID of the target attachment |
Delete an attachment to a given test execution result
DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{}
This endpoint delete a given attachment of a test execution result
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the test execution result from |
| test_run_id | The ID of the test run you want to retrieve the test execution result from |
| test_snapshot_id | The ID of the test that you want to retrieve the test execution result from |
| test_result_id | The ID of the test execution result you want |
| attachment_id | The ID of the target attachment |
Builds
What's a build?
A build is a way to group the execution results of the tests contained in a CucumberStudio test run.
You can find more details on test executions and builds in the Test execution introduction section.
List builds of a test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "builds",
"id": "1",
"attributes": {
"name": "Build 1",
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"is-running": false,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/1"
}
},
{
"type": "builds",
"id": "2",
"attributes": {
"name": "Build 2",
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"is-running": true,
"closed-at": null
},
"links": {
"self": "/builds/2"
}
}
]
}
This endpoint retrieves all builds of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the requested test run |
| test_run_id | The ID of the test run you want to retrieve the builds from |
Create a new build in a test run
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "Build 1"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"type": "builds",
"id": "3",
"attributes": {
"name": "Build 3",
"created-at": "now!",
"test-run-id": 1,
"is_running": true,
"closed_at": null
},
"links": {
"self": "/builds/3"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you are executing |
| Parameter | Description |
|---|---|
| name | The name of the build. It should not be empty and uniq |
Update a build
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "builds",
"id": <build_id>,
"attributes": {
"name": "Build 1"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "builds",
"id": "3",
"attributes": {
"name": "Build 1",
"created-at": "...",
"test-run-id": 1,
"is_running": true,
"closed_at": null
},
"links": {
"self": "/builds/3"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you are executing |
| build_id | The ID of the build you want to update |
| Parameter | Description |
|---|---|
| name | The new name of the build. |
Get a specific build of a test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "builds",
"id": "1",
"attributes": {
"name": "Build 1",
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"is-running": false,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/1"
}
},
"included": []
}
This endpoint retrieves a specific build of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| test_run_id | The ID of the test run you want to retrieve the build from |
Get test execution results of a build
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>?include=test-results HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "builds",
"id": "1",
"attributes": {
"name": "Build 1",
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"execution-environment-id": 1,
"is-running": false,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/1"
},
"relationships": {
"test-results": {
"data": [
{
"type": "test-results",
"id": "1"
},
{
"type": "test-results",
"id": "2"
}
]
}
}
},
"included": [
{
"type": "test-results",
"id": "1",
"attributes": {
"status": "passed",
"created-at": "1980-07-01T12:00:00.350Z",
"description": "",
"status-author": "Jenkins",
"step-statuses": [
"passed",
"passed",
"passed"
],
"test-snapshot-id": 1,
"execution-environment-id": 1
},
"links": {
"self": "/test-results/1"
}
},
{
"type": "test-results",
"id": "2",
"attributes": {
"status": "failed",
"created-at": "1980-07-01T12:00:00.350Z",
"description": "Error on line 42",
"status-author": "Jenkins",
"step-statuses": [],
"test-snapshot-id": 2,
"execution-environment-id": 1
},
"links": {
"self": "/test-results/2"
}
}
]
}
Use the JSONAPI include syntax to fetch the test execution results of your build.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you want to retrieve the build from |
Get the current build of a test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/current" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "builds",
"id": "1",
"attributes": {
"name": "Build 1",
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"execution-environment-id": 29,
"is-running": false,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/1"
}
},
"included": []
}
This endpoint retrieves the current build of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you want to retrieve the build from |
Get test execution results of the current build of a test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/current?include=test-results" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "builds",
"id": "1",
"attributes": {
"name": "Build 1",
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"execution-environment-id": 29,
"is-running": false,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/1"
},
"relationships": {
"test-results": {
"data": [
{
"type": "test-results",
"id": "1"
},
{
"type": "test-results",
"id": "2"
}
]
}
}
},
"included": [
{
"type": "test-results",
"id": "1",
"attributes": {
"status": "passed",
"created-at": "1980-07-01T12:00:00.350Z",
"description": "",
"status-author": "Jenkins",
"step-statuses": [
"passed",
"passed",
"passed"
],
"test-snapshot-id": 1,
"execution-environment-id": 29,
},
"links": {
"self": "/test-results/1"
}
},
{
"type": "test-results",
"id": "2",
"attributes": {
"status": "failed",
"created-at": "1980-07-01T12:00:00.350Z",
"description": "Error on line 42",
"status-author": "Jenkins",
"step-statuses": [],
"test-snapshot-id": 2,
"execution-environment-id": 29,
},
"links": {
"self": "/test-results/2"
}
}
]
}
Use the JSONAPI include syntax to fetch the test execution results of the current build of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you want to retrieve the build from |
Add a test execution result to a build
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test-results",
"attributes": {
"status": "passed",
"status-author": "Harry",
"description": "All was well"
},
"relationships": {
"test-snapshot": {
"data": {
"type": "test-snapshots",
"id": 1
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Newly created test result
{
"data": {
"type": "test-results",
"id": "1",
"attributes": {
"status": "passed",
"created-at": "Couple of miliseconds ago",
"description": "",
"status-author": "Harry"
},
"links": {
"self": "/test-results/1"
},
"relationships": {
"test-snapshot": {
"data": {
"type": "test-snapshots",
"id": "1"
},
},
"build": {
"data": {
"type": "builds",
"id": "1"
}
}
},
"included": [
{
"type": "test-snapshots",
"attributes": "test data"
},
{
"type": "builds",
"attributes": "build data"
}
]
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the tests from |
| test_run_id | The ID of the test run that contains the test you want |
| build_id | The ID of the build you want add a test result to |
Mandatory fields
| Field | Description |
|---|---|
| status | (String) The status of the test execution. Possible values are 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', 'undefined'. |
| status-author | (String) The name of the author of the test execution |
| description | (String) A comment about the test execution |
| test-snapshot | (JSONAPI relationship) The executed test |
Close a build
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>/close" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
The closed build
{
"data": {
"type": "builds",
"id": "3",
"attributes": {
"name": "Build 3",
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"is-running": false,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/3"
},
"relationships": {
"test-results": {}
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you are executing |
| build_id | The ID of the build you want to close |
Execution environments
What's an execution environment?
An execution environment is a way to group several builds by in a CucumberStudio test run.
You can find more details on test executions and execution environments in the Test execution introduction section.
List execution environments of a test run
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "execution-environments",
"id": "1",
"attributes": {
"name": "Default",
"test-run-id": 1,
"created-at": "2017-06-13T08:15:38.607Z",
"updated-at": "2018-09-09T10:48:48.685Z"
},
"links": {
"self": "/execution-environments/1"
}
},
{
"type": "execution-environments",
"id": "2",
"attributes": {
"name": "Environment 1",
"test-run-id": 1,
"created-at": "2017-06-13T08:15:38.607Z",
"updated-at": "2018-09-09T10:48:48.685Z"
},
"links": {
"self": "/execution-environments/2"
}
}
]
}
This endpoint retrieves all execution environments of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the requested test run |
| test_run_id | The ID of the test run you want to retrieve the builds from |
List builds of an execution environment
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "builds",
"id": "1",
"attributes": {
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"execution-environment-id": 1,
"is-running": true,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/1"
}
},
{
"type": "builds",
"id": "2",
"attributes": {
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"execution-environment-id": 1,
"is-running": false,
"closed-at": null
},
"links": {
"self": "/builds/2"
}
}
]
}
This endpoint retrieves all builds of a given execution environment.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project that contains the requested test run |
| test_run_id | The ID of the test run that contains the requested execution environment |
| execution_environment_id | The ID of the execution environment you want to retreive the builds from |
Create a new execution environment
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"attributes": {
"name": "Execution environment 1"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
A new execution environment
{
"data": {
"type": "execution-environments",
"id": "1",
"attributes": {
"name": "Execution environment 1",
"test-run-id": 29,
"created-at": "2019-02-22T08:59:38.603Z",
"updated-at": "2019-02-22T08:59:38.603Z"
},
"links": {
"self": "/execution-environments/1"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the folders from |
| test_run_id | The ID of the test run you are executing |
Mandatory fields
| Parameter | Description |
|---|---|
| name | The name of the execution environment. It should not be empty and uniq |
Update an execution environment name
PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environmnent_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "execution-environments",
"id": <execution_environment_id>,
"attributes": {
"name": "Android"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data":
{
"type": "execution-environments",
"id": "1",
"attributes": {
"created-at" : "2017-02-28T11:39:08.281Z",
"updated-at" : "2017-02-28T11:39:08.281Z",
"name": "Android",
"test_run_id" : 1
},
"links": {
"self": "/execution-environments/1"
}
}
}
This endpoint updates the name of an execution environment for a test run and a given project.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the action word from |
| test_run_id | The ID of the test_run that the execution environment belongs to |
| execution_environment_id | The ID of the execution environment you want to update the name |
Delete an execution environment
DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environments_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
This endpoint delete an execution environment.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the scenario from |
| test_run_id | The ID of the test_run that the execution environment belongs to |
| execution_environment_id | The ID of the execution environment to delete |
Create a new build in a specific execution environment
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
A new build
{
"data": {
"type": "builds",
"id": "3",
"attributes": {
"created-at": "now!",
"test-run-id": 1,
"execution-environment-id": 29,
"is_running": true,
"closed_at": null
},
"links": {
"self": "/builds/3"
}
}
}
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you are executing |
| execution_environment_id | The ID of the execution environment for your new build |
Get the current build of an execution environment
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds/current" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "builds",
"id": "1",
"attributes": {
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"execution-environment-id": 29,
"is-running": false,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/1"
}
},
"included": []
}
This endpoint retrieves the current build of a given test run.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you want to retrieve the build from |
| execution_environment_id | The ID of the execution environment you want to retrieve the build from |
Get test execution results of the current build of an execution environment
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds/current?include=test-results" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "builds",
"id": "1",
"attributes": {
"created-at": "2017-06-13T08:15:38.607Z",
"test-run-id": 1,
"execution-environment-id": 29,
"is-running": false,
"closed-at": "2017-06-16T09:13:48.737Z"
},
"links": {
"self": "/builds/1"
},
"relationships": {
"test-results": {
"data": [
{
"type": "test-results",
"id": "1"
},
{
"type": "test-results",
"id": "2"
}
]
}
}
},
"included": [
{
"type": "test-results",
"id": "1",
"attributes": {
"status": "passed",
"created-at": "1980-07-01T12:00:00.350Z",
"description": "",
"status-author": "Jenkins",
"step-statuses": [
"passed",
"passed",
"passed"
],
"test-snapshot-id": 1,
"execution-environment-id": 29
},
"links": {
"self": "/test-results/1"
}
},
{
"type": "test-results",
"id": "2",
"attributes": {
"status": "failed",
"created-at": "1980-07-01T12:00:00.350Z",
"description": "Error on line 42",
"status-author": "Jenkins",
"step-statuses": [],
"test-snapshot-id": 2,
"execution-environment-id": 29
},
"links": {
"self": "/test-results/2"
}
}
]
}
Use the JSONAPI include syntax to fetch the test execution results of the current build of a given execution environment.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the build from |
| test_run_id | The ID of the test run you want to retrieve the build from |
| execution_environment_id | The ID of the execution environment you want to retrieve the build from |
Add a test execution result to the current build of an execution environment
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
{
"data": {
"type": "test-results",
"attributes": {
"status": "passed",
"status-author": "Harry",
"description": "All was well"
},
"relationships": {
"test-snapshot": {
"data": {
"type": "test-snapshots",
"id": 1
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Newly created test result
{
"data": {
"type": "test-results",
"id": "1",
"attributes": {
"status": "passed",
"created-at": "Couple of miliseconds ago",
"description": "",
"status-author": "Harry"
},
"links": {
"self": "/test-results/1"
},
"relationships": {
"test-snapshot": {
"data": {
"type": "test-snapshots",
"id": "1"
},
}
"build": {
"data": {
"type": "builds",
"id": "1"
}
}
}
},
"included": [
{
"type": "test-snapshots",
"attributes": "test data"
},
{
"type": "builds",
"attributes": "build data"
}
]
}
This endpoint will create a test result in the current build of the specified execution environment.
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The ID of the project you want to retrieve the tests from |
| test_run_id | The ID of the test run that contains the test you want |
| execution_environment_id | The ID of the execution environment you want add a test result to |
Mandatory fields
| Field | Description |
|---|---|
| status | (String) The status of the test execution. Possible values are 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', 'undefined'. |
| status-author | (String) The name of the author of the test execution |
| description | (String) A comment about the test execution |
| test-snapshot | (JSONAPI relationship) The executed test |
Deprecations
Test status
Thanks to the new execution environment feature, a test is now executed on an execution environment. Consequently the status attribute of a test does not mean anything without an execution environment.
To get a test execution status, please refer Get test execution results of the current build of an execution environment
Note that the status attribute will be removed on 28 february 2020.