Extracting Variables

Variable extraction enables your tests to adjust dynamically to whatever scenario you've decided to test. You can extract auto-generated IDs from your database, or JWT tokens for use in making subsequent authorized requests.

Simple Extraction

To extract a variable from a repsonse, create an extract mapping definition on your test. The extract definition follows the exact same layout as expect, except variables placed here will be populated, instead of expanded.

In this example, the USER_ID which was auto-generated by the db is extracted, as well as the authorization token.

  - test: "Sign up"
    description: "Signing up as a new user for the site"

    request:
      method: POST
      url: "${BASE_URL}/auth/signup"
      headers:
        Content-Type: application/json
      body:
        email: ${USER_EMAIL}
        displayName: john-smith
        password: ${USER_PASSWORD}

    expect:
      status: 2xx
      headers:
        Content-Type: $regex /json/
      body:
        id: $exists
        email: ${USER_EMAIL}
        displayName: john-smith
        password: $absent

    extract:
      headers:
        Authorization: Bearer ${AUTH_TOKEN}
      body:
        id: ${USER_ID}

Those collected variables can then be used in subsequent requests. In the following example, the USER_ID we collected is used as a URL path param, and the AUTH_TOKEN we collected is used to authenticate the request.

  - test: "Access profile data"
    description: "After signing in, the user can get their profile data"

    request:
      method: GET
      url: ${BASE_URL}/user/${USER_ID}
      headers:
        Authorization: Bearer ${AUTH_TOKEN}

    expect:
      status: 2xx
      body:
        firstName: $exists
        lastName: $exists
        imageUrl: $regex /.*\.png$/

Embedded Extraction

Notice in the above extract example that ${AUTH_TOKEN} is placed after "Bearer" - this ensures that only the token is extracted, and not the word "Bearer". That's not particularly useful in this case since the word "Bearer" is still going to be used in subsequent tests anyway, however there are some cases where needed values are embedded in long strings of content. This extraction works as if the entire string were a regex with your variable as a capture group.

For example, if your extract definition has the following:

  extract:
    body:
      message: The quick ${COLOR} fox jumped over the ${ADJECTIVE} dog.

And the actual response looks like this:

  body:
    message: The quick brown fox jumped over the lazy dog.

Then the resulting values for ${COLOR} and ${ADJECTIVE} will evaluate to "brown" and "lazy", respectively.

Considerations

• Extracted variables cannot be used in suites with the configuration option parallel: true set. This is because tests running in parallel cannot reference variables extracted from each other.
• Currently, extracted values can only be strings. Unlike statically defined variables, you cannot extract entire mappings or sequences from a response.
• Using extracted variables in subsequent tests creates an inherent dependency of those tests on the test which performs the extraction. If a test with an extract definition fails, all its dependent tests will fail as well. Keep this in mind when you see many failures - it may just be one test causing the issue.