API Module

The API module provides steps for testing HTTP APIs. It supports three backends — stdlib (urllib, default), httpx (requires [api]) and requests — and covers configuration, requests, assertions and response storage.

Installation

pip install "behave-steplib[api]"        # httpx backend
pip install "behave-steplib[requests]"   # requests backend

The stdlib backend (urllib) is always available with no extra dependencies. Install the [api] extra to use httpx, or the [requests] extra to use requests.

Backends

Backend	Package	Notes
stdlib	(none)	Default. Uses urllib from the standard library. No extra dependencies.
httpx	httpx	HTTP/2 support, async-capable, cookie persistence. Requires the [api] extra.
requests	requests	Session-based with cookie persistence. Requires the [requests] extra.

Select a backend via autoload:

autoload(context, backends={"api": "httpx"})
autoload(context, backends={"api": "requests"})
autoload(context, backends={"api": "stdlib"})  # default, no extra needed

Steps

The API module provides 55 steps organised into eight categories. All steps have es and pt translations unless noted otherwise.

Configuration

Pattern	Description
the API base url is {url}	Set the base URL for subsequent requests.
I set the API header {name} to {value}	Set a default header sent with every request.
I set the API timeout to {seconds:d} seconds	Set the request timeout in seconds.
I set the query parameter {name} to {value}	Set a default query parameter sent with every request.
I remove the query parameter {name}	Remove a previously set query parameter.
I remove the header {name}	Remove a previously set default header.
I clear the request data	Reset headers, params, auth, cookies, and last response.
I set the proxy to {url}	Set a proxy URL for both HTTP and HTTPS requests.

Authentication

Pattern	Description
I set basic authentication with username {user} and password {password}	Set basic auth credentials for subsequent requests.
I set the bearer token to {token}	Set a Bearer token in the Authorization header.

SSL and redirects

Pattern	Description
I disable SSL verification	Disable SSL certificate verification for subsequent requests.
I enable SSL verification	Enable SSL certificate verification for subsequent requests.
I disable redirects	Disable following redirects for subsequent requests.
I enable redirects	Enable following redirects for subsequent requests.
I save cookies from the response	Extract Set-Cookie headers from the last response and store them.

Requests

Pattern	Description
I send a {method} request to {url}	Send an HTTP request and store the response.
I send a {method} request to {url} with body	Send a request with a body from the step’s text (context.text).
I send a {method} request to {url} with form data	Send a request with form-encoded data from the step table.
I send a {method} request to {url} with JSON body	Send a request with a JSON body from the step’s text.
I send a {method} request to {url} with query parameters	Send a request with query parameters from the step table.
I send a {method} request to {url} with headers	Send a request with extra headers from the step table.

The {method} placeholder accepts any HTTP method string (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). Relative URLs are resolved against the base URL set with the API base url is.

Status and body assertions

Pattern	Description
the response status is {status:d}	Assert the last response status code.
the response status is one of {statuses}	Assert the status is one of a comma-separated list (e.g. 200, 201, 202).
the response body contains {text}	Assert the response body contains a substring.
the response body does not contain {text}	Assert the response body does not contain a substring.
the response body is valid JSON	Assert the response body is valid JSON.
the response matches the JSON schema	Validate the response body against a JSON Schema from the step text.

JSON Path assertions

Pattern	Description
the JSON path {path} equals {value}	Assert a JSON path in the response equals a value.
the JSON path {path} does not equal {value}	Assert a JSON path value does not equal a value.
the JSON path {path} exists	Assert that a JSON path exists in the response.
the JSON path {path} contains {value}	Assert a JSON path value contains a value (for lists or strings).
the JSON path {path} is null	Assert that a JSON path value is null.
the JSON path {path} is not null	Assert that a JSON path value is not null.
the JSON path {path} has length {length:d}	Assert a JSON path value (list or string) has a specific length.
the JSON path {path} has type {type}	Assert the value at a JSON path is of a specific type.
the JSON path {path} matches the pattern {pattern}	Assert a JSON path string value matches a regex pattern.

Header assertions

Pattern	Description
the response header {name} is {value}	Assert a response header equals a value.
the response header {name} is not {value}	Assert a response header does not equal a value.
the response header {name} contains {value}	Assert a response header contains a substring.
the response has header {name}	Assert that a response header exists.
the response does not have header {name}	Assert that a response header does not exist.
the response content type is {content_type}	Assert the Content-Type response header equals a value.
the response content type contains {content_type}	Assert the Content-Type response header contains a substring.

Response time assertions

Pattern	Description
the response time is less than {seconds:d} seconds	Assert the response time is under a threshold.
the response time is greater than {seconds:d} seconds	Assert the response time exceeds a threshold.
the response time is between {min:d} and {max:d} seconds	Assert the response time is within a range.

Store and extract

Pattern	Description
I store the response body as {variable}	Store the response body as a named variable.
I store the JSON path {path} as {variable}	Store the value at a JSON path from the response as a variable.
I store the response header {name} as {variable}	Store a response header value as a named variable.
I store the response status as {variable}	Store the last response status code as a named variable.
I store the response time as {variable}	Store the last response time in milliseconds as a variable.
I use the variable {variable} as the header {name}	Set a header from a previously stored variable.
I use the variable {variable} as the query parameter {name}	Set a query parameter from a previously stored variable.
the variable {variable} equals {value}	Assert that a stored variable equals a value.

Table comparison

Pattern	Description
the response matches the table	Compare the response JSON with a behave table. Requires the [tables] and [kit] extras.

Example

Feature: API health check

  Scenario: GET users returns 200
    Given the API base url is "https://api.example.com"
    When I send a GET request to "/users"
    Then the response status is 200
    And the response body is valid JSON
    And the JSON path "$.users[0].name" equals "Ada"

  Scenario: POST creates a user
    Given the API base url is "https://api.example.com"
    When I send a POST request to "/users" with body
      """
      {"name": "Ada", "email": "ada@example.com"}
      """
    Then the response status is 201
    And the response header "Content-Type" is "application/json"
    And I store the response body as "created_user"

JSONPath syntax

The the JSON path {path} equals {value} step supports a simple JSONPath subset:

• $ — the root object.

• $.field — access a field.

• $.field.nested — nested access.

• $.items[0] — array index.

Examples:

Then the JSON path "$" equals "..."
Then the JSON path "$.users" equals "..."
Then the JSON path "$.users[0].name" equals "Ada"
Then the JSON path "$.items[2].price" equals "19.99"

API reference

See Modules API Reference for the full autodoc reference of the API module.