API Testing

Test suites in AegisRunner can mix browser-based UI steps with direct HTTP calls. The api-request step type lets you assert on REST or GraphQL endpoints without spinning up a browser — fast, cheap, and easy to chain into UI flows for end-to-end coverage.

What you get

• HTTP requests: GET, POST, PUT, PATCH, DELETE.
• Custom headers, cookies, query parameters.
• JSON body or form-encoded body.
• Assertions on status code, response body (with JSON path), response headers, and timing.
• Mixed UI + API in a single test (sign in via UI, hit API to verify, continue UI flow).

Adding an API step

1. Open a test, click + Add step.
2. Step type: API request.
3. Method: GET / POST / PUT / PATCH / DELETE.
4. URL — full URL or relative to your base URL.
5. Headers, body, query params as needed.
6. Assertions — what should be true about the response.

Assertions

Assertion	Example
Status code	status = 200 or status < 300
JSON path equals	response.user.id = 123
JSON path exists	response.token exists
JSON path matches regex	response.email matches /^.+@.+$/
Array length	response.items.length = 5
Response time	responseTime < 500 (milliseconds)
Header present	headers.X-Request-ID exists
Header value	headers.Content-Type = application/json

JSON paths use dot notation, with [N] for array indexes: response.users[0].email.

Using tokens and variables

All step fields support variable substitution:

method:  POST
url:     {{API_BASE}}/orders
headers:
  Authorization: Bearer {{API_KEY}}
  Content-Type:  application/json
body:
  customerId: '{{CUSTOMER_ID}}'
  items: [{ sku: 'A1', qty: {{ORDER_QTY}} }]
assertions:
  - status = 201
  - response.id exists
  - responseTime < 1000

Variables come from Test Environment tokens and form data set rows.

Mixing UI and API steps

The most powerful pattern. Here's a checkout flow with API verification interleaved:

1. navigate     /products/SKU-A1
2. click        button:has-text("Add to cart")
3. api-request  GET {{API_BASE}}/cart
   assert:      response.items.length = 1
4. navigate     /checkout
5. fill         input[name="email"] = {{email}}
6. click        button:has-text("Place order")
7. wait         url matches /orders/.*
8. assert       h1:has-text("Order confirmed") visible

UI flow drives the user behavior; API steps verify backend state at each stage. Catches bugs that pure-UI tests miss (e.g. the order says confirmed in the UI but is actually still pending in the database).

GraphQL

POST to your GraphQL endpoint with a JSON body containing query and variables:

method: POST
url:    {{API_BASE}}/graphql
headers:
  Authorization: Bearer {{API_KEY}}
body:
  query: |
    query GetUser($id: ID!) {
      user(id: $id) {
        id
        email
        name
      }
    }
  variables:
    id: '{{USER_ID}}'
assertions:
  - status = 200
  - response.data.user.email = '{{EXPECTED_EMAIL}}'
  - 'response.errors' not exists

Authentication patterns

Bearer token

Store the token under Test Environment → Tokens as API_KEY, reference as Authorization: Bearer {{API_KEY}}.

Session-based (sign in first)

Run a UI sign-in step first; subsequent API steps inherit the cookies automatically. The browser context is shared across UI and API steps.

API-only sign-in (when your endpoint accepts a static token)

If your environment has a long-lived test token, store it under Test Environment → Tokens as API_KEY and reference it directly in API steps. For flows that require dynamic per-request tokens (e.g. login → grab a session token → use it), pair an API step with a UI sign-in so the browser session carries the auth — API steps inherit cookies from the same session.

API steps and visual regression

API steps don't capture screenshots — there's nothing to capture. They show in the run timeline but don't contribute to visual regression.

Performance assertions

Use responseTime < N to fail tests on slow API responses. Common thresholds:

• Read endpoints: 500ms.
• Write endpoints: 1500ms.
• Search/aggregate: 3000ms.

The threshold counts time-to-first-byte, not full response body. Tune to your SLA.

Plan availability

Plan	API steps
Free	—
Starter	✓
Pro / Business / Enterprise	✓

Common questions

Can I test internal-only APIs?

If they're reachable from AegisRunner's IPs (we publish a list under Settings → API Access). For VPC-only APIs, Enterprise self-host is the path.

How do I test webhooks I send to my own service?

Use AegisRunner's request inspector — set up an outgoing webhook in your config that posts to a temporary URL we provide. Tests can assert the inspector saw the expected payload. Available on Pro+.

Can I parameterize an API test across many inputs?

Yes — pair with a form data set. Each row becomes a separate run of the same API test.

Are response bodies stored?

Yes, for the run's retention window (7 days Free up to 1 year Business). Available on the run page for debugging. Sensitive fields can be masked via custom assertions.

Related

• Test Data Management — tokens for API auth.
• User Flow Tests — mixing UI and API steps.
• API Overview — AegisRunner's own management API.