Triggering Scenarios by URL
In addition to being able to run tests through Stoplight and the terminal, scenarios can also be run by issuing a HTTP request.
To trigger a scenario by URL, there are two methods:
-
Issuing a HTTP
GET
request, which runs the collection with the project’s default settings and configuration. -
Issuing a HTTP
POST
request, which runs the collection with variables populated by the request’s JSON body. This is necessary if you have passwords or other sensitive pieces of data that are not stored in Stoplight, but are required for running the scenario.
Finding the Scenario URL
Every scenario has a unique URL that can be used to remotely trigger the scenario. To find this URL:
-
Go to the scenario’s summary in Stoplight
-
Below the scenario summary is a “Trigger This Collection” section
-
Within this section is a “Trigger by URL” containing the URL unique to this scenario
Triggering Scenarios
If the scenario is part of a public project and does not require any
customization to be run, then it can be triggered by issuing a simple HTTP GET
request to the scenario’s URL, as shown below.
$ curl 'https://oihdflk5hiyltnnsxelttmnsw4ylsnfxxgltznvwa.prism.stoplight.io/'
{
"status": "completed",
"failCount": 3,
"passCount": 6,
"time": 555.3748400000001,
"env": {
...
To customize the scenario’s variables (i.e., to add passwords and other sensitive
information), they can either be included as URL query parameters in the GET
request, or included within the request body of a POST
request.
Customizing Variables with Query String Parameters
You can customize the variables included in the scenario at runtime by adding extra query string parameters to the URL.
For example, if you have an api_token
variable that is required to run your
scenario, it can be added to the scenario by attaching the ?api_token=abc123
query string to the URL (where abc123
is the value of the api_token
variable).
Customizing Variables with a HTTP POST Body
In addition to adding a query string parameter, scenario variables can also be
updated by using a HTTP POST
request instead of a GET
request. When using
this method, the POST
body must be composed of JSON with the JSON keys
corresponding to the variables within the scenario.
Similar to the example above, if you have an api_token
variable that is
required to run your scenario, issuing a HTTP POST
with the following JSON
body will inject the variable into the scenario runtime.
{
"api_token": "abc123"
}
To issue a POST
request from the CLI, you can use the curl
command. For
example:
$ curl -XPOST \
--data-binary '{"api_token":"abc123"}' \
'https://oihdflk5hiyltnnsxelttmnsw4ylsnfxxgltznvwa.prism.stoplight.io/'
{
"status": "completed",
"failCount": 3,
"passCount": 6,
"time": 555.3748400000001,
"env": {
...
Triggering Scenarios in Private Projects
Public project scenarios can be triggered directly through the scenario URL with no further action needed. Private projects, however, must have an API token specified so that the request can be authenticated properly. To generate a new API token for your Stoplight acccount, see here.
Once you have an API token, set it under the JWT Token
header in order for
it to be used to authenticate with the Stoplight API. For example:
$ curl -H 'Authentication Header: H4BTDASDf5sGHMWJSfE32' ...
Be sure to keep all private tokens safe! They can be used to authenticate requests with any project that your account has access to.
Related Articles