IntroductionGetting StartedAuthenticationRequestsConcept: Providing Credentials (or other data)Concept: Instruction GranularityResponses
WebhooksExamplesIntegration Test

Requests will be expecting a JSON payload in your request body when triggering a test run. This payload is responsible for specifying what is being tested, how it's being tested, and any additional data that may be necessary to carry out that testing.

name: string (required)A name to associate with the test. This will be displayed in your results.
url: string (required)The URL of the web application being tested.
instructions: string[] (required)The sequential series of steps that should be taken to carry out the test.
variables: object[{ string: string }]A map of variables to be interpolated with the test instructions (see Providing Credentials below).
revision: stringAn optional revision tag, such as a commit id, to associate with the test. This will be displayed in your results.
1walrus -a YOUR_API_TOKEN -u -n 'Search' -i \
2 'Enter "walrus" in the search bar' \
3 'Hit enter' \
4 'Make sure results are displayed'

Concept: Providing Credentials (or other data)

There may be times when you need to specify credentials or other data for to use when executing an integration test. Some examples could be providing a test credit card number, or a specifically prepared account to be logged in to.

Any time you find yourself needing to provide additional data, use the variables request parameter to pass in the additional data. These variables can then be referenced directly in your test url or instructions using the format :variable_name: (note the colons before and after).

By default, considers data passed in via the variables object to be sensitive it will not be included in the dashboard or integration results (Slack or Custom Webhook). If you want to add non-sensitive metadata in your test, you can add a ! to the end of the key name.

1# Run with "walrus -a YOUR_API_TOKEN -f /path/to/this/file.yml"
3name: 'Sign-up Test'
4url: ''
6 username!: 'username'
7 password: 'password'
9 - 'Sign up with username :username!:, password :password:'
10 - 'Sign the terms and conditions'
11 - 'Go to inbox'

Sometimes, you may want to add metadata from the environment. When using the CLI tool, you can interpolate environment variables directly in your test files.

1# Run with "walrus -a YOUR_API_TOKEN -f /path/to/this/file.yml"
3name: 'Sign-up Test'
4url: 'https://:environment!'
6 environment!: $DEPLOY_ENVIRONMENT
8 - 'Log in'
9 - 'Sign the terms and conditions'
10 - 'Go to inbox'

Concept: Instruction Granularity

Imagine our company offers an email client as an alternative to Gmail. Our product has a lengthy onboarding flow and we want to ensure that new customers can finish the flow regardless of any future updates we make. This sounds like the perfect scenario for an end-to-end test!

First, let's walk through what steps an end-user would need to take to complete this onboarding process:

  1. Navigate to
  2. Click "Register"
  3. Sign in with Google (third-party flow)
  4. Read + accept legal forms
  5. Proceed through a multi-step product tour
  6. Click "Okay" to continue to the inbox
  7. Compose an email

Since our instructions for are just an array of string instructions, translating these steps into an API request should be straight forward.

1walrus -a YOUR_API_TOKEN -u -i \
2 "Sign up with Google" \
3 "Sign the terms and conditions" \
4 "Proceed past inbox tour" \
5 "Proceed past compose tour" \
6 "Proceed past settings tour" \
7 "Go to inbox" \
8 "Compose an email and make sure it saves to drafts"

There's one big thing to note here: the instruction granularity is completely up to you.

In a traditional end-to-end test, you would have to specify your instructions just as a computer would expect them: step-by-step, with no room for interpretation or judgment. Thanks to the combination of and human judgment, such specificity no longer necessary. Our complex onboarding flow, which spans navigation, third-party authentication, and form submission are all handled with a single instruction: "Sign up with Google".

However, when you do want increased granularity, perhaps for making stricter or more numerous assertions, that's also easy to accomplish with In our example above we specified each individual product tour step that we'd expect. Such specificity ensures we don't erroneously stop displaying a specific onboarding step to users.