PHP and API server for Behat tests

✨ Features

• PhpServerContext - starts and stops PHP's built-in web server around each scenario:
  • Serves files from a configurable document root.
  • Configurable protocol, host and port.
  • Tag a scenario or a whole feature with @phpserver to opt in.
• API server that replays queued responses:
  • Step definitions to queue responses inline, as JSON, or from a fixture file.
  • Step definitions to assert how many requests arrived and how many responses are still queued.
  • Records every received request for debugging.
  • Tag a scenario or a whole feature with @apiserver to opt in.

📦 Installation

composer require --dev drevops/behat-phpserver

Coming from 2.x? See UPGRADE.md - the step phrases are unchanged, but some method names moved.

🚀 Usage

Register the contexts in behat.php:

PhpServerContext

Serves static assets from a pre-defined document root.

This context adds no step definitions. It starts the server before a tagged scenario and stops it afterwards, so tag the scenarios that need it:

Tagging the Feature: line instead starts the server for every scenario in that feature.

Reach the running server through getServerUrl() - see Accessing the server URL from your own context.

ApiServerContext

Serves pre-set API responses. It extends PhpServerContext, so it accepts the same options plus paths.

Context options

PhpServerContext requires webroot. ApiServerContext defaults it to the bundled apiserver directory.

Both contexts default to port 8888. When both are registered, give each one its own port, as shown above.

behat.dist.php sets every option for both contexts.

📖 Step definitions

Server lifecycle

Queueing responses

Responses are replayed in the order they were queued, one per request.

Assertions and debugging

Both assertion steps also accept the alternative phrasings the API server should have received 3 requests and the API server should have 0 responses queued, and both accept a singular noun for a count of one.

See the test feature for worked examples of every step.

File responses

API will respond with file reads a file from the configured paths, searching each path in the order given until it finds a match. The content type is derived from the file extension:

Accessing the server URL from your own context

To point an API client at the running server, read the URL in a #[BeforeScenario] hook:

🔌 API server HTTP endpoints

The step definitions cover the common cases. The mock server also exposes the endpoints directly, which is useful when driving it from code rather than from Gherkin.

Any other method on one of these endpoints is refused with 405 Method Not Allowed and an Allow header listing the methods it accepts. A refused request is not recorded and the response queue is left untouched.

These endpoints and the replayed responses carry an X-Received-Requests and an X-Queued-Responses header with the current counts. Error responses do not.

Any other request is recorded and answered with the next queued response. When the queue is empty, the server answers 500 with No responses in queue.

An error response carries its message in the status line and in a JSON body, such as {"error":"No responses in queue"}.

PUT /admin/responses takes an array of response objects:

body must be base64-encoded - the server decodes it before replaying the response. The step definitions do this encoding for you, so it only matters when calling the endpoint directly. code must be between 100 and 599, reason must be a non-empty string, and headers must be an object with scalar values. A payload that breaks these rules is refused with 400, and none of its responses are queued.

🤝 Contributing

See CONTRIBUTING.md for local setup, linting, testing and maintenance.

This repository was created using the Scaffold project template