atoum / apiblueprint-extension
Compile and run tests written in the API Blueprint format (`.apib`) with atoum
Requires
- php: >7.0
- ext-curl: *
- ext-mbstring: *
- atoum/atoum: ~3.2
- hoa/ustring: ~4.0
- justinrainbow/json-schema: ~5.2
- league/commonmark: ~0.16
Requires (Dev)
- hoa/dispatcher: ~1.0
- hoa/router: ~3.0
This package is auto-updated.
Last update: 2021-09-20 08:28:42 UTC
README
atoum/apiblueprint-extension
The candidates:
- atoum is a PHP test framework,
- API Blueprint is a high-level HTTP API description language.
The problem: API Blueprint is only a text file. Easy to read for human, but a machine can't do anything with it.
The solution: Compile API Blueprint files into executable tests. It works as any test written with the atoum API, and it works within the atoum ecosystem. Here is an overview of the workflow:
In more details, here is what happens:
- A finder iterates over
.apib
files, - For each file, it is parsed into an intermediate representation,
- The intermediate representation is compiled to target “atoum tests”,
- The fresh tests are pushed in the test queue of atoum,
- atoum executes everything as usual.
The bonus: A very simple script is provided to render many API Blueprint files as a standalone HTML single-page file.
Installation and configuration
With Composer, to include this extension into
your dependencies, you need to
require
atoum/apiblueprint-extension
:
$ composer require atoum/apiblueprint-extension '~0.2'
To enable the extension, the .atoum.php
configuration file must be edited to add:
$extension = new atoum\apiblueprint\extension($script); $extension->addToRunner($runner);
Configure the finder
Assuming the .apib
files are located in the ./apiblueprints
directory, the following code adds this directory to the API Blueprint
finder, compiles everything to tests, and enqueue them:
$extension->getAPIBFinder()->append(new FilesystemIterator('./apiblueprints')); $extension->compileAndEnqueue();
Configure the location of JSON schemas when defined outside .apib
files
API Blueprint uses JSON Schema to validate HTTP requests and responses when the message aims at being a valid JSON message.
We recommend to define JSON schemas outside the .apib
files for several reasons:
- They can be versionned independently from the
.apib
files, - They can be used inside your application to validate incoming HTTP requests or outgoing HTTP responses,
- They can be used by other tools.
To do so, one must go through these 2 steps:
- Mount a JSON schema directory with the help of the extension's configuration,
- Use
{"$ref": "json-schema://<mount>/schema.json"}
in the Schema section.
Example:
-
In the
.atoum.php
file where the extension is configured:$extension->getConfiguration()->mountJsonSchemaDirectory('test', '/path/to/schemas/');
-
In the API Blueprint file:
+ Response 200 + Schema {"$ref": "json-schema://test/api-foo/my-schema.json"}
where
test
is the “mount point name”, and/api-foo/my-schema.json
is a valid JSON schema file located at/path/to/schemas/api-foo/my-schema.json
.
Testing
Before running the test suites, the development dependencies must be installed:
$ composer install
Then, to run all the test suites:
$ composer test
Compliance with the API Blueprint specification
This atoum extension implements the API Blueprint specification.
Language features | Implemented? |
---|---|
Metadata section | yes |
API name & overview section | yes |
Resource group section | yes |
Resource section | yes |
Resource model section | no (ignored) |
Schema section | yes |
Action section | yes |
Request section | yes |
Response section | yes |
URI parameters section | no (ignored) |
Attributes section | no (ignored) |
Headers section | yes |
Body section | yes |
Data Structures section | no (ignored) |
Relation section | no (ignored) |
License
Please, see the LICENSE
file. This project uses the same license than atoum.