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

Requires PHP 8.2 or newer.

composer require --dev drevops/behat-phpserver

🚀 Usage

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

ApiServerContext defaults webroot to the bundled apiserver directory. PhpServerContext has no usable default, so always set it.

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

📖 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.

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.

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; header names and values must be scalars.

🤝 Contributing

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

This repository was created using the Scaffold project template