### Start Development Server

Source: https://github.com/imbo/behat-api-extension/blob/main/features/README.md

Starts the PHP built-in web server for testing purposes. Ensure the document root is set to the 'bootstrap' directory. This command may take a while to complete.

```bash
composer dev --timeout=0
```

--------------------------------

### Install with Composer

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/installation.md

Use this command to add the behat-api-extension as a development dependency to your project.

```bash
composer require --dev imbo/behat-api-extension
```

--------------------------------

### v2 behat.yml Configuration

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

Example configuration for v2 of the extension, demonstrating the 'apiClient.base_uri' structure.

```yaml
default:
  suites:
    default:
      # ...

  extensions:
    Imbo\BehatApiExtension:
      apiClient:
        base_uri: http://localhost:8080

```

--------------------------------

### v1 Request Body Syntax

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

Example of how to set the request body using a simple string in v1 of the extension.

```gherkin
Given the request body is "some data"
```

--------------------------------

### v1 behat.yml Configuration

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

Example configuration for v1 of the extension, showing the 'base_uri' option.

```yaml
default:
  suites:
    default:
      # ...

  extensions:
    Imbo\BehatApiExtension:
      base_uri: http://localhost:8080

```

--------------------------------

### Configure Behat API Extension with Guzzle Options

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/configuration.md

Configure the Imbo\BehatApiExtension with specific Guzzle client options. This example sets the base URI, timeout, and SSL verification.

```yaml
default:
  suites:
    default:
      # ...

  extensions:
    Imbo\BehatApiExtension:
      apiClient:
        base_uri: http://localhost:8080
        timeout: 5.0
        verify: false
```

--------------------------------

### Example Usage of Custom @gt Matcher

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/extending-the-extension.md

Demonstrates how to use the custom '@gt' matcher function within a Gherkin feature file to assert that a JSON number is greater than a specified value.

```gherkin
Then the response body contains JSON:
    """
    {
      "number": "@gt(40)"
    }
    """
```

--------------------------------

### Register Custom Matcher Function for JSON

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/extending-the-extension.md

Add custom matcher functions to the ArrayContainsComparator to extend JSON response verification capabilities. This example adds a '@gt' function.

```php
<?php
use Imbo\BehatApiExtension\Context\ApiContext;
use Imbo\BehatApiExtension\ArrayContainsComparator;

class FeatureContext extends ApiContext
{
    /**
     * Add a custom function called @gt to the comparator
     */
    public function setArrayContainsComparator(ArrayContainsComparator $comparator): self
    {
        $comparator->addFunction('gt', function ($num, $gt) {
            $num = (int) $num;
            $gt = (int) $gt;

            if ($num <= $gt) {
                throw new InvalidArgumentException(sprintf(
                    'Expected number to be greater than %d, got: %d.',
                    $gt,
                    $num
                ));
            }
        });

        return parent::setArrayContainsComparator($comparator);
    }
}
```

--------------------------------

### Get OAuth Token using Password Grant

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Requests an OAuth token using the password grant flow. The token is added as an Authorization header for subsequent requests. The endpoint must return a JSON object with an 'access_token' key.

```gherkin
Given I get an OAuth token using password grant from "/token" with "user" and "password" in scope "scope" using client ID "id" and client secret "secret"
When I request "/path/that/requires/token/in/header"
```

--------------------------------

### Activate Behat API Extension

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/configuration.md

Activate the Imbo\BehatApiExtension in your `behat.yml` file. This is the minimal configuration required.

```yaml
default:
  suites:
    default:
      # ...

  extensions:
    Imbo\BehatApiExtension: ~
```

--------------------------------

### Configure API Client Initialization

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/extending-the-extension.md

Customize the internal GuzzleHttp\Client by overriding the initializeClient method to add middleware or modify default configurations.

```php
<?php
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use Imbo\BehatApiExtension\Context\ApiContext;

class FeatureContext extends ApiContext
{
    public function initializeClient(array $config): static
    {
        $stack = $config['handler'] ?? HandlerStack::create();
        $stack->push(Middleware::mapRequest(
            fn ($req) => $req->withAddedHeader('Some-Custom-Header', 'some value')
        ));
        $config['handler'] = $stack;
        return parent::initializeClient($config);
    }
}
```

--------------------------------

### Sending File Path in v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

The method for sending file paths has changed. v1 allowed direct inclusion in the When step, while v2 requires using a Given step for the request body.

```gherkin
When I send "/some/file.jpg" to "/some/endpoint" using HTTP POST
```

```gherkin
When I send "/some/file" as "application/json" to "/some/endpoint" using HTTP POST
```

```gherkin
Given the request body contains "/some/file.jpg"
When I request "/some/endpoint" using HTTP POST
```

```gherkin
Given the request body contains "/some/file"
And the "Content-Type" request header is "application/json"
When I request "/some/endpoint" using HTTP POST
```

--------------------------------

### v2 Request Body Syntax with PyStringNode

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

Demonstrates the updated syntax for setting the request body using a PyStringNode in v2.0.0. This allows for multi-line request bodies.

```gherkin
Given the request body is:
    """
some data
    """
```

--------------------------------

### Set Basic Authentication

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Configure basic authentication for the next request using a username and password.

```gherkin
Given I am authenticating as "foo" with password "bar"
```

--------------------------------

### Registering and Verifying a JWT Token

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

This snippet demonstrates how to first register a JWT with a specific identifier and secret, and then verify its presence and validity in an API response using the @jwt() matcher.

```gherkin
# Register the JWT
Given the response body contains a JWT identified by "my JWT", signed with "secret":
    """
    {
        "user": "Some user"
    }
    """

# Other steps ...

# After the request has been made, one can match the JWT in the response
And the response body contains JSON:
    """
    {
      "value": "@jwt(my JWT)"
    }
    """
```

--------------------------------

### Add Custom Steps to FeatureContext

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/extending-the-extension.md

Extend the ApiContext to add custom @Given, @When, or @Then steps by defining methods with appropriate docblock annotations.

```php
<?php
use Imbo\BehatApiExtension\Context\ApiContext;
use Imbo\BehatApiExtension\Exception\AssertionFailedException;

class FeatureContext extends ApiContext
{
    /**
     * @Then I want to check something
     */
    public function assertSomething()
    {
        // do some assertions on $this->response, and throw a AssertionFailedException
        // exception if the assertion fails.
    }
}
```

--------------------------------

### Execute Behat Tests

Source: https://github.com/imbo/behat-api-extension/blob/main/features/README.md

Runs the Behat tests using the composer script. This is the primary command for verifying API extension functionality.

```bash
composer test:behat
```

--------------------------------

### Set Multiple Query Parameters at Once

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Sets multiple query parameters with their respective values for the upcoming request. Any query parameters in the request path are ignored when this step is used.

```gherkin
Given the following query parameters are set:
    | name | value |
    | foo  | bar   |
    | bar  | foo   |
When I request "/path"
```

--------------------------------

### Setting Request Body in v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

In v1, the request body could be set directly in the When step. In v2, it must be set using a Given step.

```gherkin
When I request "/some/path" using HTTP POST with body:
    """
    {"some":"data"}
    """
```

```gherkin
Given the request body is:
    """
    {"some":"data"}
    """
When I request "/some/path" using HTTP POST
```

--------------------------------

### Set Multipart Form Parameters

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Set form parameters for a multipart request. This step defaults to POST and sets the `Content-Type` to `multipart/form-data`. It cannot be used with a request body.

```gherkin
Given the following multipart form parameters are set:
    |
    | name | value |
    | foo  | bar   |
    | bar  | foo   |
    | bar  | bar   |
```

--------------------------------

### Execute Behat Tests Directly

Source: https://github.com/imbo/behat-api-extension/blob/main/features/README.md

Alternatively, execute Behat tests directly using the vendor binary. The --strict flag enforces stricter test execution.

```bash
./vendor/bin/behat --strict
```

--------------------------------

### Setting JSON Request Body and Content-Type in v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

In v1, JSON body could be set directly in the When step. In v2, the body and Content-Type header must be set using Given steps.

```gherkin
When I request "/some/path" using HTTP POST with JSON body:
    """
    {"some":"data"}
    """
```

```gherkin
Given the request body is:
    """
    {"some":"data"}
    """
And the "Content-Type" request header is "application/json"
When I request "/some/path" using HTTP POST
```

--------------------------------

### Array Minimum Length Response Assertion v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

A minor clarification change was made to the assertion step for an array minimum length, adding 'JSON' in v2.

```gherkin
Then the response body is an array with a length of at least 5
```

```gherkin
Then the response body is a JSON array with a length of at least 5
```

--------------------------------

### Set Request Body from File

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Sets the request body to the content of a specified file. The 'Content-Type' header is automatically determined based on the file's mime type. The mime type can be overridden using the 'Given the :header request header is :value' step.

```gherkin
Given the request body contains "/path/to/file"
```

--------------------------------

### Array Length Response Assertion v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

A minor clarification change was made to the assertion step for an array length, adding 'JSON' in v2.

```gherkin
Then the response body is an array of length 5
```

```gherkin
Then the response body is a JSON array of length 5
```

--------------------------------

### Empty Object Response Assertion v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

A minor clarification change was made to the assertion step for an empty object response, adding 'JSON' in v2.

```gherkin
Then the response body is an empty object
```

```gherkin
Then the response body is an empty JSON object
```

--------------------------------

### Empty Array Response Assertion v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

A minor clarification change was made to the assertion step for an empty array response, adding 'JSON' in v2.

```gherkin
Then the response body is an empty array
```

```gherkin
Then the response body is an empty JSON array
```

--------------------------------

### Set Form Parameters

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Sets form parameters for a POST request with 'application/x-www-form-urlencoded' content type by default. If combined with file attachments, content type becomes 'multipart/form-data'. Cannot be used with a request body.

```gherkin
Given the following form parameters are set:
    | name | value |
    | foo  | bar   |
    | bar  | foo   |
    | bar  | bar   |
```

--------------------------------

### Numeric Comparison: Less Than

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Utilize the `@lt` function to verify that a numeric value in the response is strictly less than a specified value. Applicable to integers, doubles, and numeric strings.

```gherkin
And the response body contains JSON:
    """
    {
      "some-int": "@lt(125)",
      "some-double": "@lt(1.25)",
      "some-string": "@lt(125)"
    }
    """
```

--------------------------------

### Assert Array Min Length with Custom Matcher

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Asserts the minimum length of a JSON array using the `@arrayMinLength` custom matcher. Use this when the array size must meet a certain threshold.

```gherkin
Then the response body contains JSON:
    """
    {"items": "@arrayMinLength(3)"}
    """
```

--------------------------------

### Set Multiple Values for a Single Query Parameter

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Sets multiple values for a single query parameter for the upcoming request. Any query parameters in the request path are ignored when this step is used.

```gherkin
Given the query parameter "foo" is:
    | value |
    | foo   |
    | bar   |
When I request "/path"
```

--------------------------------

### Assert Exact Response Body

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Asserts that the response body exactly matches the provided text. The comparison is case-sensitive. Use this for verifying precise string outputs.

```gherkin
Then the response body is:
    """
    {"foo":"bar"}
    """
```

```gherkin
Then the response body is:
    """
    foo
    """
```

--------------------------------

### Renamed v1 to v2 Methods in ApiContext

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

Illustrates the renaming of public methods in the ApiContext class for v2 compatibility. Use these new method names in your Behat feature files.

```gherkin
Given I attach a file to the request
Given I authenticate as "user" with password "pass"
Given the request header is "Accept: application/json"
given the following form parameters are set:
  | name  | value |
  | key   | value |
Given the request body is "some data"
Given the request body is a file resource "/path/to/file.txt"
When I request "/users"
Then the response code is 200
Then the response code is not 404
Then the response reason phrase is "OK"
Then the response status line is "HTTP/1.1 200 OK"
Then the response is "some data"
Then the response is not "some data"
Then the response header "Content-Type" exists
Then the response header "Content-Type" does not exist
Then the response header "Content-Type" is "application/json"
Then the response header "Content-Type" matches "application/json"
Then the response body is an empty JSON object
Then the response body is an empty JSON array
Then the response body is an array of length 5
Then the response body is an array with a length of at least 3
Then the response body is an array with a length of at most 10
Then the response body is "{\"key\": \"value\"}"
Then the response body matches "{\"key\": \"value\"}"
Then the response body contains JSON "{\"key\": \"value\"}"
```

--------------------------------

### Assert Response Body Not Equal

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Asserts that the response body does not match the provided text. The comparison is case-sensitive. Useful for ensuring specific content is absent.

```gherkin
Then the response body is not:
    """
    some value
    """
```

--------------------------------

### Attach File to Request

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Attach a file to the request, which will populate the `$_FILES` array on the server. This causes a `multipart/form-data` request. Relative paths are resolved from the working directory. This step cannot be used with a request body.

```gherkin
Given I attach "/path/to/file.jpg" to the request as "file1"
```

```gherkin
Given I attach "c:\some\file.jpg" to the request as "file2"
```

```gherkin
Given I attach "features/some.feature" to the request as "feature"
```

--------------------------------

### Array Maximum Length Response Assertion v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

A minor clarification change was made to the assertion step for an array maximum length, adding 'JSON' in v2.

```gherkin
Then the response body is an array with a length of at most 5
```

```gherkin
Then the response body is a JSON array with a length of at most 5
```

--------------------------------

### Set Single Query Parameter

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Sets a single query parameter to a specific value for the upcoming request. Any query parameters in the request path are ignored when this step is used.

```gherkin
Given the query parameter "foo" is "bar"
And the query parameter "bar" is "foo"
When I request "/path"
```

--------------------------------

### Assert Array Max Length with Custom Matcher

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Asserts the maximum length of a JSON array using the `@arrayMaxLength` custom matcher. Use this when the array size should not exceed a certain limit.

```gherkin
Then the response body contains JSON:
    """
    {"items": "@arrayMaxLength(10)"}
    """
```

--------------------------------

### Response Body Contains Assertion v1 vs v2

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/installation/upgrade.md

A minor clarification change was made to the assertion step for response body content, adding 'JSON' in v2.

```gherkin
Then the response body contains:
    """
    {"some": "value"}
    """
```

```gherkin
Then the response body contains JSON:
    """
    {"some": "value"}
    """
```

--------------------------------

### Validating Root-Level Numeric Array Elements

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

For JSON responses where the root node is a numerical array, use bracket notation like `[index]` to access and validate individual elements.

```gherkin
Then the response body contains JSON:
    """
    {
      "[0]": "foo",
      "[1]": 123,
      "[2]":
      {
        "foo": "bar"
      },
      "[3]": "@regExp(/bar/)",
      "[4]": "@arrayLength(3)"
    }
    """
```

--------------------------------

### Set Request Header

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Sets a specific request header to a given value. If the header is set multiple times, the last value will be used. Be cautious when combining with other steps that modify headers, as it can lead to undefined behavior.

```gherkin
Given the "User-Agent" request header is "test/1.0"
```

```gherkin
Given the "Accept" request header is "application/json"
```

--------------------------------

### Matching JSON Values with Regular Expressions

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Employ the `@regExp` function to validate string, integer, or float/double values against a provided regular expression. The value is cast to a string before the match. Ensure the regex includes delimiters and optional modifiers.

```gherkin
Then the response body contains JSON:
    """
    {
      "foo": "@regExp(/(some|expression)/i)",
      "bar":
      {
        "baz": "@regExp(/[0-9]+/)"
      }
    }
    """
```

--------------------------------

### Assert Array Length with Custom Matcher

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Asserts the exact length of a JSON array using the `@arrayLength` custom matcher. This is useful for verifying the size of collections within the response.

```gherkin
Then the response body contains JSON:
    """
    {"items": "@arrayLength(5)"}
    """
```

--------------------------------

### Assert Response Body Matches Regex

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Asserts that the response body matches a given regular expression pattern. The pattern must be a valid regex, including delimiters and modifiers. Use for flexible pattern matching.

```gherkin
Then the response body matches:
    """
    /^{"FOO": ?"BAR"}$/i
    """
```

```gherkin
Then the response body matches:
    """
    /foo/
    """
```

--------------------------------

### Numeric Comparison: Greater Than

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Use the `@gt` function to assert that a numeric value in the response is strictly greater than a specified value. This works for integers, doubles, and strings that can be cast to numbers.

```gherkin
Then the response body contains JSON:
    """
    {
      "some-int": "@gt(120)",
      "some-double": "@gt(1.20)",
      "some-string": "@gt(120)"
    }
    """
```

--------------------------------

### Assert Response Body Contains JSON (Subset)

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Recursively matches the response body against a JSON blob, asserting a subset of the response. Useful for verifying specific fields within a larger JSON structure.

```gherkin
Then the response body contains JSON:
    """
    {
      "string": "string value",
      "bool": true
    }
    """
```

--------------------------------

### Accessing Array Elements by Index in JSON

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

When dealing with numerically indexed arrays in JSON, use the `key[index]` notation to target specific elements for assertion. This applies to nested arrays as well.

```gherkin
Then the response body contains JSON:
    """
    {
      "items[0]": "foo",
      "items[1]": "@regExp(/(foo|bar|baz)/)",
      "items[2]":
      {
        "some":
        {
          "foo": "@regExp(/ba(r|z)/)"
        }
      },
      "items[3]": "@arrayLength(3)"
    }
    """
```

--------------------------------

### Assert JSON Array Content

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Asserts specific values within a JSON array in the response body, including checking for specific elements and their types. Note: Order does not matter for basic matching.

```gherkin
Then the response body contains JSON:
    """
    {
      "array":
      [
        true,
        "string value",
        {
          "integer": 123
        }
      ]
    }
    """
```

--------------------------------

### Register JWT Payload for Matching

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Registers a JWT with a specific name and secret, allowing its payload to be matched against custom data. The payload can include custom matcher functions.

```gherkin
Given the response body contains a JWT identified by "my JWT", signed with "some secret":
    """
    {
        "some": "data",
        "value": "@regExp(/(some|expression)/i)"
    }
    """
```

--------------------------------

### Add to Request Header

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Adds a value to an existing request header. If the header is repeated, it will be converted into an array. This is useful for headers that can have multiple values.

```gherkin
Given the "X-Foo" request header contains "Bar"
```

--------------------------------

### Set Request Body from PyString

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/setup-request.md

Sets the request body to a string defined within a PyStringNode. This is useful for sending JSON or other string-based payloads.

```gherkin
Given the request body is:
    """
    {
        "some": "data"
    }
    """
```

--------------------------------

### Assert JSON Object Content

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Asserts specific values within nested JSON objects in the response body. Allows targeting deeply nested fields for verification.

```gherkin
Then the response body contains JSON:
    """
    {
      "object":
      {
        "string": "string value",
        "object":
        {
          "null": null,
          "integer": 123
        }
      }
    }
    """
```

--------------------------------

### Asserting Variable Types in JSON Response

Source: https://github.com/imbo/behat-api-extension/blob/main/docs/guide/verify-server-response.md

Use the `@variableType` function to assert the data type of values within a JSON response. Supported types include bool, int, double, string, array, object, null, and scalar. You can also use aliases like boolean for bool.

```gherkin
Then the response body contains JSON:
    """
    {
      "bool value": "@variableType(bool)",
      "int value": "@variableType(int)",
      "double value": "@variableType(double)",
      "string value": "@variableType(string)",
      "array value": "@variableType(array)",
      "object value": "@variableType(object)",
      "null value": "@variableType(null)",
      "scalar value": "@variableType(scalar)"
    }
    """
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.