API Monitoring & Testing: Integrating with Build, Continuous Integration, Deployment and Hosting Tools

Trigger URLs allow you to initiate one or more tests from scripts, code and third-party services by making simple HTTP requests.

Trigger URLs require a paid Runscope subscription.

Initiating a Test Run with a Trigger URL

The Trigger URL responds to any GET or POST request made to it. If a third-party service supports webhooks, use the Trigger URL as the value when configuring the hook. You can find the Trigger URL for a test in the Environment Settings.

The runscope_environment parameter specifies which configuration settings to use for the given test run. The full Trigger URL can be found in the Trigger URL section of the environment editor. If the parameter is omitted, the default environment for a test is used.

Each Trigger URL has a rate limit of 10 triggers over a 10 second period. If you exceed this rate limit the trigger URL will respond with an HTTP 429 status code.

Request

GEThttps://api.runscope.com/radar/:trigger_id/trigger?runscope_environment=:environment_uuid

POSThttps://api.runscope.com/radar/:trigger_id/trigger?runscope_environment=:environment_uuid

Response

{
    "data": {
        "runs": [
            {
                "agent": null,
                "bucket_key": "ujy2zddfsj",
                "region": "us1",
                "status": "init",
                "test_id": "2637778b-26c1-41c6-80ef-a9bb145fe8ff",
                "test_name": "Android Integration Tests",
                "environment_id": "ab234cdf-26c1-41c6-80ef-a9bb145fe8ff",
                "environment_name": "Production",
                "test_run_id": "df359b71-56d1-42f3-ab50-5e517a848ac7",
                "test_url": "https://www.runscope.com/radar/ujy2zddfsj/2637778b-26c1-41c6-80ef-a9bb145fe8ff",
                "test_run_url": "https://www.runscope.com/radar/ujy2zddfsj/2637778b-26c1-41c6-80ef-a9bb145fe8ff/results/df359b71-56d1-42f3-ab50-5e517a848ac7",
                "variables": {
                    "baseUrl": "https://staging.yourapihere.com",
                    "accessToken": "xyzzy",
                    "tokenSecret": "shhhhhhhh"
                }
            }
        ],
        "runs_failed": 0,
        "runs_started": 1,
        "runs_total": 1
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}
Data Attributes
runs An array of one or more test runs that were initiated with this request to the Trigger URL.
runs.agent The ID of the Radar agent used to execute this test. If a Runscope location was used, null.
runs.bucket_key The bucket key of the test being run.
runs.region The region code for the Runscope location used to execute the test run. If an agent was used, null.
runs.status Immediate test status (e.g. init or queued).
runs.test_id The unique ID for this test.
runs.test_name The name of the test.
runs.environment_id The unique ID of the environment used for this test run.
runs.environment_name The name of the environment used for this test run.
runs.test_run_id The unique ID for this test run.
runs.test_url The dashboard URL for this test to edit test settings.
runs.test_run_url The dashboard URL for this test run to view results.
runs.variables The combined state of Initial Variables (from settings and those passed into the Trigger URL) used for this run.
runs_failed The number of test runs that could not be started.
runs_started The number of test runs that were sucessfully queued to run.
runs_total The total number of test runs submitted.

Trigger URLs with Custom Initial Variables

By default, the Trigger URL will start a test run with the settings defined in the test editor. You can also start a test run with custom Initial Variables and callback URLs by passing parameters to the test's Trigger URL.

Any key=value parameters you send to a Trigger URL will be passed to your test as Initial Variables. The custom variables can be specified in URL parameters when making a GET request, or as form parameters when making a POST request. Variables that start with runscope_ are reserved for specifying values to override other test settings (see below).

Request

GEThttps://api.runscope.com/radar/:trigger_id/trigger?baseUrl=https://yourapihere.com&apiKey=abc123

POSThttps://api.runscope.com/radar/:trigger_id/trigger

When using POST, specify initial variables as form parameters in the request body with Content-Type: application/x-www-form-urlencoded.

Initial Variable Precedence

Custom variables set in Trigger URLs take precedence over those specified in the test editor. If you're using Initial Variables in a shared environment or Initial Scripts, see Variables — Evaluation Order.

Reserved Trigger URL Parameters

runscope_environment The UUID of the environment settings to use for this test run. Can be either a test-specific or shared environment (within the same bucket).
runscope_notification_url The URL to notify when the test run completes. See Notifications: Webhook for payload examples.
runscope_agent The UUID of the Radar agent used to execute this test run's requests. Parameter can be specified more than once to initiate test runs from multiple agents in a single request (e.g. runscope_agent=<uuid>&runscope_agent=<uuid>. When specified, the locations selected in the test's settings are ignored.
runscope_region The region code(s) for the locations to initiate a test run in. Parameter can be specified more than once to initiate test runs from multiple regions in a single request (e.g. runscope_region=us1&runscope_region=eu1. When specified, the locations selected in the test's settings are ignored.

Batch Trigger URL: All Tests in a Bucket

You can trigger a test run for all tests within a bucket (similar to clicking 'Run All' from the test list) using the bucket-wide Trigger URL. Locate the URL by going to your test list page and selecting Bucket Settings.

The runscope_environment parameter specifies which configuration settings to use for the set of batch test runs. Since this is running different tests, you can only specify a shared environment UUID to use. If the parameter is omitted, the default environment for a test is used.

Request

GEThttps://api.runscope.com/radar/bucket/:trigger_id/trigger

POSThttps://api.runscope.com/radar/bucket/:trigger_id/trigger

Response

The Bucket-wide Trigger URL returns a standard Trigger URL response.


Batch Trigger URL: Single Test with Multiple Initial Variable Sets

The Batch Trigger URL allows you to queue up to 50 test runs at one time using different sets of initial variables, specified in the request's body as JSON. A run will be created for each object in the array, creating initial variables for each of the attribute/value pairs. Each test will use its default environment if the runscope_environment parameter is not specified, and parameters specified in the batch request take precedence over environment settings.

Request

POSThttps://api.runscope.com/radar/:trigger_id/batch

Sample Request Data
Content-Type: application/json[
    {
        "runscope_environment": "your_environment_uuid",
        "baseUrl" : "http://staging.example.com",
        "apiKey": "xyzzy"
    },
    {
        "baseUrl" : "https://prod.example.com",
        "apiKey": "123456"
    }
]

Response

The Batch Trigger URL returns a standard Trigger URL response.


Using Trigger URLs with Third-party Services

Many services allow you to configure a webhook to be notified when a commit, build or deploy is completed. Here are instructions for using the Trigger URL with popular continuous integration, source control and hosting services.


AWS CodePipeline

CodePipeline is a continuous delivery and release automation service from Amazon Web Services. Runscope API test steps can be integrated from the AWS CodePipeline Console.

To add an API test to your CodePipeline workflow, create a new Action in your Pipeline. Choose 'Testing' as the Action category, and Runscope will be available as a Test provider. The 'Connect' button will open the Runscope integration in a new tab.

Choose which test you'd like to integrate and a location to run it in. Then select 'Create Integration' to finish the configuration. Tests will run using the default environment.

Learn more about CodePipeline by visiting Amazon Web Services.


CircleCI

You can read our CircleCI Integration tutorial here for more information on how to add Runscope API tests as part of your build process.

Alternatively, you can also use CircleCI webhooks by adding the following entry to your circle.yml file and starting a test run when your build completes. CircleCI docs.

notify:
  webhooks:
    # The Trigger URL from the test settings that looks like this example
    - url: https://api.runscope.com/radar/b6a22e79-f98f-9ec3f0d6bd02/trigger

Codeship

You can read our Codeship Integration tutorial here for more information on how to add Runscope API tests as part of your build process.


GitHub Service Hook

To start a test run after a commit has been received enter the Trigger URL into a repo's WebHook URLs located under Settings > Service Hooks.


Heroku Deploy Hook

To start a test after a successful Heroku deploy, register the Trigger URL by adding the deployhooks add-on. Replace the example URL with the Trigger URL from your test's settings page.

$ heroku addons:add deployhooks:http --url=https://api.runscope.com/radar/b6a22e79-f98f-9ec3f0d6bd02/trigger

Jenkins Build Step

To initiate a test run as a build step in your project pipeline, install the Runscope Plugin from within Jenkins. This plugin waits for a test run to complete (or timeout). If the test run is successful, the build continues to the next step. If the test run isn't successful, the plugin marks the build as a failure. Learn more details about installation and usage in the plugin instruction guide.


Jenkins Webhook

To initiate a test run after a Jenkins build, install the Notification Plugin and configure it to use the following settings:

Protocol: HTTP
URL: Your test's Trigger URL

The Notification Plugin executes the Trigger URL but does not wait for the test to complete it's run. If a triggered test fails, it will not have any effect on the Jenkins build status.


TeamCity Webhook

Mangopay has created a plugin to add Runscope API tests to your TeamCity builds. Download the plugin on Github.


Zapier

Integrate with 250+ services including Jira, BitBucket, New Relic, Windows Azure, Asana, Trello, HipChat, Campfire and more using the Runscope app on Zapier. Learn more in the Zapier Integration Guide.


Next: Notifications →