Download the PHP package stromcom/http-smoke without Composer

stromcom/http-smoke

Fast, simple and extensible HTTP smoke-testing toolkit for PHP 8.4+.

A fluent DSL for declaring HTTP smoke tests, parallel execution, capture chains between requests, cookie-shared session flows, pluggable variable sources (.env, JSON, OS env, your own), pluggable reporters (console, JSON, Markdown, HTML, GitHub Actions step summary, your own), and a small DI container so any service can be swapped without forking the package.

Features

• PHP 8.4+ — readonly classes, enums, strict types, no legacy cruft.
• Fluent DSL — declarative test definitions in plain PHP.
• Parallel execution — curl_multi-based, concurrency configurable.
• Session chains — share cookies across a sequence of requests, run sequentially.
• Capture variables — captureJsonPath('hash', 'data.thread.hash') then {@hash} in subsequent URLs / bodies / headers.
• Variable substitution — {ENV_VAR} placeholders resolved from .env, smokeHttp.json, OS env, CLI overrides — or any custom VariableSourceInterface.
• Pluggable reporters — console, JSON (canonical artefact), Markdown, standalone HTML (browsable, with filters and chain context), GitHub step summary; add your own by implementing ReporterInterface.
• Pluggable HTTP client — default is curl_multi; implement HttpClientInterface to swap in a mock or alternative backend.
• Retry — per-test or per-group retry on any failure (useful for eventually-consistent endpoints), independent 5xx retry budget.
• Circuit breaker — per-group maxFailures skips remaining tests once a group is clearly broken.
• PHPStan level max + strict rules, no docblock noise.

Quick start

1. Install

2. Create test definitions

tests/SmokeHttp/api-01-basic.php:

3. Provide variables

Either via .env.dev:

…or tests/smokeHttp.json:

4. Run

CLI reference

Options take their value either with = or as the next argument:

Unknown options, missing values, non-numeric numbers and stray positional arguments are hard errors (exit code 3) — the runner never silently ignores a flag it does not know, so a typo like --output-htlm= cannot quietly skip your report.

Exit codes: 0 success · 1 tests failed · 2 config error · 3 usage error.

DSL cheat-sheet

Available expectations

Captures

Use captureJsonPath('name', 'data.x.y') (or captureHeader('name', 'X-Foo')) on any request, then reference {@name} in any later request's URL, body, or header value.

Configuration files

The package merges configuration from several layers (later wins):

1. Defaults
2. smoke.config.php (PHP — for registering custom services / closures)
3. smokeHttp.json (per-environment static values)
4. .env.<environment>
5. OS environment variables (getenv())
6. CLI options (--base-url, --var=KEY=VALUE, …)

smokeHttp.json

smoke.config.php

Extending

Custom variable source

Implement Stromcom\HttpSmoke\Variable\VariableSourceInterface:

Custom reporter

Implement Stromcom\HttpSmoke\Reporting\ReporterInterface (onStart, onResult, onEnd) and add it via $config->extraReporters[] = new MyReporter().

Custom HTTP client

Implement Stromcom\HttpSmoke\Http\HttpClientInterface and register in the container via $config->configureContainer.

JSON report schema

The JSON report is the canonical machine-readable artefact. Markdown, HTML and GitHub step-summary outputs are derived from it.

HTML report

One self-contained file — no CDN, no assets, no server. Open it in a browser or publish it as a CI artefact. It embeds the canonical JSON and renders:

• summary cards + pass/fail/skip ratio bar, environment / duration / concurrency meta,
• groups with per-group tallies; failed tests are expanded by default,
• per-test detail: method, URL, HTTP code, duration, attempts (total time incl. retries),
• all failure messages verbatim, skip reasons,
• payloads — the request exactly as sent (headers incl. the implicit Content-Type, query parameters, body in its wire encoding) and the response (headers, pretty-printed body), plus a ready-to-run cURL reproduction,
• source — the definition file and line of each test (tests/SmokeHttp/api/users.php:24), as plain selectable text,
• chain context for session tests — every preceding step of the session (method, status, label, URL, duration) with the failing step highlighted,
• filters: full-text search (label / URL / failure message / payload / path), status (all / failed / passed / skipped), group, definition file, retried-only, sessions-only, plus expand/collapse all and “show payloads”.

Dark mode follows the OS setting. The layout logic lives in src/Reporting/templates/report.html; HtmlReporter only injects the JSON.

Payloads and secrets

Payloads land in both the JSON and the HTML report, so treat those artefacts as sensitive. Sensitive headers (Authorization, Cookie, Set-Cookie, X-Api-Key, …) are replaced with «redacted», bodies are truncated at 16 kB and binary bodies are reported as size only.

Examples

See examples/ for ready-to-run test suites and a sample smoke.config.php / smokeHttp.json.

License

MIT — see LICENSE.