Tutorial: Your First API Test

Build a two-step API test that authenticates against a REST endpoint, captures the access token, chains it into a second request, and validates the response — all without writing code.

Who is this for? Developers and SDETs new to API testing in ContextQA. You will build one test case that authenticates against an API, chains the token into a second request, and validates the response.

API testing in ContextQA lets you send HTTP requests, assert response values, and chain data between calls — all from the same visual test editor you use for browser tests. Instead of writing scripts in Postman or pytest, you add REST API steps to a test case and let ContextQA handle execution, evidence capture, and failure analysis.

In this tutorial you will:

  1. Create an API test case with a GET request

  2. Add status code and payload validation

  3. Store the response and chain it into a second request

  4. Run the test and review per-step results

End result: A two-step API test that authenticates, captures a token, calls a protected endpoint with that token, and validates the returned data — with full execution evidence (request/response logs, timing, and pass/fail status per step).

Prerequisites

  • A ContextQA account with at least one workspace (sign up)

  • A REST API you can test against (a public API or your own staging environment)

  • The API's base URL, an authentication endpoint (if applicable), and at least one data endpoint

  • Familiarity with core concepts — specifically test cases, steps, and variables


Step 1: Create a test case with an API step

Start by creating a test case that sends a single GET request and confirms the API responds successfully.

  1. In the left sidebar, click the Test Development icon.

  2. Click the + button and select Start recording.

  3. Enter a name for your test case: API — User endpoint validation.

  4. In the step editor, type rest in the step search field and select Rest API method from the list.

  5. Click the three dots icon on the step to open the API testing panel.

The panel displays fields for HTTP method, URL, headers, body, response storage, and validation.

  1. Set the HTTP method to GET.

  2. Enter your target endpoint URL. For example:

  1. Click Send to execute the request interactively. The panel displays the response body, status code, and headers.

Verify it worked: The response panel shows a 200 status code and a JSON body containing user data. If you see a 401 or 403, you need authentication — skip ahead to Step 3 to add an auth step first.

Tip: Use the interactive Send button to preview responses before saving the step. This lets you inspect the JSON structure and plan your validation assertions before committing to a test step.


Step 2: Add response validation

A test that sends a request without asserting the response passes even when the API returns wrong data. Add validation to catch regressions.

Add a status code assertion

  1. In the API testing panel, scroll to the Validation section.

  2. Set the data type to status.

  3. Set the comparator to equal.

  4. Enter 200 as the expected value.

This assertion fails the step if the API returns any status other than 200.

Store the response for later use

  1. In the Store response field, enter a variable name: userResult.

  2. Click Create to save the step.

The full response — status code, headers, and body — is now stored in userResult. You can reference any field using dot notation: userResult.body.email, userResult.body.name, userResult.headers.content-type.

Add a payload assertion

  1. Click the three dots icon on the saved step to reopen the API testing panel.

  2. In the Validation section, add a second assertion.

  3. Enter a JSON path to a field you want to verify. For example, if the response contains an email field:

  1. Set the data type to string, the comparator to Equals, and enter the expected value (for example, [email protected]).

  2. Click Create Update to save.

Verify it worked: The step now shows two validation badges — one for status code, one for the payload field. Run the test case by clicking Run in the top toolbar. Open the execution results and confirm both assertions pass with green checkmarks.

Important: If you are unsure of the exact JSON path, run the step once without payload validation. Open Run History, select the step, and navigate to the Response Body tab to see the full JSON structure. Use that structure to construct the correct path.


Step 3: Chain an authenticated request

Most real APIs require authentication. In this step, you add an authentication call before the GET request and chain the resulting token into the second step's headers.

Add an auth step

  1. In the test case step list, click Add Step above your existing GET step so the auth step runs first.

  2. Type rest and select Rest API method.

  3. Open the API testing panel and configure the authentication request:

Field
Value

HTTP method

POST

URL

https://api.example.com/auth/login (your auth endpoint)

Headers

Content-Type: application/json

Body

{"username": "[email protected]", "password": "TestPass123!"}

  1. Under Store response, enter authResult.

  2. In Validation, add a status code assertion: status equal 200.

  3. Click Create to save.

After this step runs, the access token is available at authResult.body.access_token (adjust the path to match your API's response structure).

Inject the token into the GET step

  1. Open the API testing panel on your existing GET step (step 2 in the test case).

  2. In the Headers section, add a new header:

Key
Value

Authorization

Bearer ${authResult.body.access_token}

  1. Click Create Update to save.

At execution time, ContextQA resolves ${authResult.body.access_token} using the live token from step 1. Because the token is captured fresh on every run, the test works even when tokens expire between sessions.

Verify it worked: Run the full test case. Both steps should pass:

Step
Expected outcome

Step 1 (POST /auth/login)

Status 200, token stored in authResult

Step 2 (GET /users/1)

Status 200, Authorization header resolved, payload assertion passes


Step 4: Run and review the results

With both steps configured, run the complete test case and review the evidence.

  1. Click Run in the top toolbar.

  2. Select an execution environment from the dialog and click Run.

  3. The execution begins. Each API step shows a real-time pass/fail indicator as it completes.

When execution finishes, click View Detailed Report.

What to check in the results

Step-by-step breakdown — each step shows:

  • Pass/fail status for every validation assertion

  • The full request sent (method, URL, headers, body)

  • The full response received (status code, headers, body)

  • Execution duration per step

Response Body tab — select any step to inspect the raw JSON response. Use this to:

  • Confirm variable values were resolved correctly (check that ${authResult.body.access_token} was replaced with an actual token in step 2's request headers)

  • Copy JSON paths for additional assertions you want to add later

  • Diagnose unexpected response structures

Network log — the Network tab shows every HTTP request made during execution, including timing and status codes. Use this to identify slow endpoints or unexpected redirects.

Result
What it means

Both steps pass

Authentication and data retrieval work correctly

Step 1 fails (auth)

Credentials are wrong, the auth endpoint changed, or the API is down

Step 1 passes, step 2 fails

The token is valid but the data endpoint has an issue — check the status code and response body


Summary

You built a complete API test in four steps:

  1. Created an API test case with a GET request using the REST API step type

  2. Added validation — a status code assertion and a payload assertion targeting a specific JSON field

  3. Chained an authentication call by storing the auth response in a variable and injecting the token into the next step's headers

  4. Ran the test and reviewed per-step results including request/response details and assertion outcomes

One test case now validates authentication and data retrieval in a single automated flow.

Next steps

  • Add more assertions: Validate additional response fields — check that userResult.body.id is a number, that userResult.body.roles contains the expected values, or that userResult.headers.content-type equals application/json.

  • Import from a Swagger specification: If your API has an OpenAPI spec, import it to generate test cases for every endpoint and status code combination automatically. See Creating API tests.

  • Add structure validation: Assert the full response shape to catch field additions or removals between deployments. See Validating responses.

  • Build hybrid API + UI tests: Chain an API response into a browser step — for example, create a user via the API and then verify the user appears in the UI. See API chaining.

  • Run in CI/CD: Add your API test to a test plan and trigger it from GitHub Actions or Jenkins on every pull request. See GitHub Actions or Jenkins.

Test your API in minutes — no code required. Start Free Trial → — Or Book a Demo → to see API testing with your endpoints.

Last updated

Was this helpful?