README

That sounds like "spa", but plural.
It tests your API description against a given environment using real HTTP requests.

Note

Spas is currently alpha, so its API is subject to change!

How It Works / Example

There is a running example in the example dir including a readme to follow along.

In order to use spas, you'll need:

your api description parser, e.g. drafter for api blueprint
spas itself, which is api description agnostic
spas-request-parser implementation, to understand your api description parse result

Running spas looks like:

get parse result from your api description parser
call spas with it

Installation

From Source

The recommended way to install spas & co is by using composer.

API Description Parser

In this example, we'll install drafter to work with API Blueprint.

composer require hmaus/drafter-installer

Now configure the drafter installer accordingly. Make sure to actually install drafter, usually you'll add a script to call composer install-drafterduring the config, and check it using vendor/bin/drafter -v.

Request Parser

Please see a guide to create a request parser if your parser is not yet supported

composer require hmaus/spas-parser-apib

This will get you \Hmaus\Spas\Parser\Apib\ApibParsedRequestsProvider to put into spas' request_provider option

Spas

Now we can install spas itself:

composer require hmaus/spas

With a default composer config, spas should now be available as vendor/bin/spas.

Hooks

The hook system is what makes spas pretty flexible. It allows you to add bits and pieces of code to manipulate requests, assert outcomes and much more.

There are a few pre-built hooks for you to examine and try out.
Simply browse /src/Hook to see pre-built hooks; all the ones prefixed with Hello are examples to learn from.

Run Hook

Take your spas command add an option:

--hook "Hmaus\Spas\Hook\HelloWorld"

As you can see, the hooks are simply passed using their fully qulified class name. So as long as the classes sit inside thee autloader, you can use them right away.

To pass multiple hooks, simply repeat the --hook option for every one of them.

--hook "Hmaus\Spas\Hook\HelloWorld"
--hook "Hmaus\Spas\Hook\HelloHookData"

Pass Data to Hooks

Many of your hooks shall be flexible in what they can do, hence you want to configure them from the outside.
We suggest to use JSON format to pass data into a hook like so:

--hook "Hmaus\Spas\Hook\HelloHookData"
--hook_data $'{
    "Hmaus-Spas-Hook-HelloHookData": {
        "apikey": "ewifvweilfvf"
    },
    "Your-Namespace-SomeOtherHook": {
        "hook-data-option": "contains all data passed to all hooks"
    }
}'

Note that you need to replace the backslashes with dashes for the --hook_data.
Let me know if you know how to make it work with the backslashes.

Write Your Own Hooks

Once you examine the existing hooks, you should already gathered all there is to know.
Create a new class that is ato-loadable, extend \Hmaus\Spas\Hook\Hook, implement the one abstract method and check Hook's API and the pre-built examples for best practices.

hmaus / spas

Maintainers

Details