Compile API Blueprint files into executable tests with atoum
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
res
src
test
.atoum.php
.bootstrap.atoum.php
.gitignore
.travis.yml
LICENSE
README.md
composer.json

README.md

atoum's extension logo

atoum/apiblueprint-extension Build Status

The candidates:

  1. atoum is a PHP test framework,
  2. 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:

Process overview

In more details, here is what happens:

  1. A finder iterates over .apib files,
  2. For each file, it is parsed into an intermediate representation,
  3. The intermediate representation is compiled to target “atoum tests”,
  4. The fresh tests are pushed in the test queue of atoum,
  5. 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:

  1. Mount a JSON schema directory with the help of the extension's configuration,
  2. Use {"$ref": "json-schema://<mount>/schema.json"} in the Schema section.

Example:

  1. In the .atoum.php file where the extension is configured:

    $extension->getConfiguration()->mountJsonSchemaDirectory('test', '/path/to/schemas/');
  2. 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)

Any help is welcomed!

License

Please, see the LICENSE file. This project uses the same license than atoum.