Behat extension for those who want to write acceptances tests for apis

Baptiste Clavié

Last update: Nov 25, 2022

Related tags

API api php rest bdd behat php71 behat-extension behat-contexts

Overview

Behapi

Behat extension to help write describe features related to HTTP APIs.

PHP 7.3, Behat 3.7 and a discoverable php-http client are required to make this extension work.

Installing this extension requires you to require taluu/behapi and an implementation of a http client (providing psr/http-client-implementation ^1.0, psr/http-factory-implementation ^1.0 and psr/http-message-implementation ^1.0).

You can find some examples on the examples/ directory.

Howto

Add this in your behat.yml (it's for the default configuration but you can use it for any configurations actually) :

default:
  suites:
    main:
      paths: ['%paths.base%/features']
      services: '@Behapi\Container'
      autowire: true

      contexts:
        #- List
        #- your
        #- contexts
        #- here

        # examples :
        - Behapi\Http\RequestContext: ~
        - Behapi\Http\ResponseContext: ~

  extensions:
    Behapi\Behapi:
      base_url: 'http://localhost'

The base_url is the only requirement in the config for this extension to work.

There are other configurations keys, such as which formatter to use in a debug environment, which headers you want to output in request or response while debugging ; Use the --config-reference flag when invoking behat to have more information on the available configuration.

After having installed the extension, you can then use the provided contexts such as the Behapi\Http\RequestContext for the http api operations. In order to use them, you need to use behapi's container (@Behapi\Container), or a container capable of using behapi's container.

Some services are provided to be injected in contexts, which are the following:

@Http\Client\Common\PluginClientBuilder, which will build a Http\Client\Common\PluginClient when needed
@Behapi\HttpHistory\History, which is a sort of a container with the last requests done and last responses received
@Http\Message\MessageFactory
@Http\Message\StreamFactory

Note: You don't really need to bother with the services names, as they are compatible with behat's auto-wiring feature.

In order to enable the Json assertions, you need to use the Behapi\Context\Json context. Note that if you use the json context, you should have used the client provided by the client builder used in the Behapi\Http\RequestContext context.

If you need to play with the request being built, or the response created when the request is sent, you need to inject the @Behapi\HttpHistory\History. It is automatically reseted between scenarios (and scenarios outlines)

A documentation will be made (soon hopefully) with more details.

Contributing

Contributing (issues, pull-requests) are of course always welcome ! Be sure to respect the standards (such as psr-2, ... etc), follow proper git etiquette (atomic commits, ...), proper conduct too and it should be fine !

Thanks

This extension was made while I was working at @Wisembly, and heavily used for writing our features and integration tests. Special thanks goes to @lunika, @rgazelot and @krichprollsch, who helped conceived this extension, and also pushed me to open-source it.

Badges

Comments

fix: nullable parameter order in the Json Context for php 8.1

Prior to PHP 8.1, the method isDefaultValueAvailable() on optional parameter declared before a required parameter would return true. That not the case anymore with php 8.1. See https://onlinephp.io/c/3c36e

As it's something used by Behat to construct arguments of a step, it breaks as Behat doesn't add the argument anymore (see https://github.com/Behat/Behat/blob/master/src/Behat/Testwork/Argument/MixedArgumentOrganiser.php#L408). In the Json context of Behapi (and probably elsewhere, didn't check everything), there is nullable parameter before required parameter. final public function the_json_path_should_be_equal_to(string $path, ?string $not = null, $expected): void

I didn't touch the the_json_path_should_be_py_string because I think multiline argument are always passed as the last argument in Behat. So a rewrite or a split of the function is needed.

opened by Titoine 2
Generate code coverage from behapi test ?

Would be a really nice feature if we could generate code coverage using phpunit code coverage tool :

https://github.com/sebastianbergmann/php-code-coverage

But from my understanding, since we are hitting the API from an external process, we cannot get proper code coverage through xdebug ? Is there a way around that ?
question wontfix

opened by mhlsf 2
Refactor how the debug is handled
Fixes #24 : Move the DebugRest context into a proper listener

[x] Move the damn thing

[x] Change the necessary tag from @api to @http

[x] Make it work for all kind of scenarios (Background, Scenario and ScenarioOutline)

[x] Debug why on ScenarioOutline only the last request is debugged (and not the other ones)

[x] Add more specific debug options (like something allowing to debug moar, through composition : see https://github.com/Taluu/Behapi/pull/25#issuecomment-290147534)

[x] Rename the --api-debug into --behapi-debug (as --debug is already taken, and was changed thanks to @lunika in #1)
opened by Taluu 2

Discuss about @api tag

As discussed, we have to use the tag @api to use --api-debug and the @debug tag.

Baptiste Clavié [6:18 PM] 
je voulais avoir genre soit `@rest` soit `@api`

[6:18]  
mais je pense que je vais opter pour `@rest`

[6:18]  
(parce que `DebugRest`)

[6:18]  
ou alors `DebugApi`

[6:19]  
voir `DebugHttp` en fait, ca devrait avoir plus de sens

Remy Gazelot [6:19 PM] 
+1

Baptiste Clavié [6:20 PM] 
du coup faudrait que j'introduise un tag `@http` (edited)

opened by rgazelot 2

content-type header harcoded

The content-type header is harcoded here https://github.com/Taluu/behat-api/blob/master/context/Rest.php#L45

I think you should remove it because for some requests (GET for example) there is no body, so no content-type and all rest api doesn't have a json content-type. This info should be set for each requests or find a way via an abstract method or configuration to set this value by the lib integrator

opened by lunika 2
Use Symfony HttpClient instead of HttpPlug ?

This would mean a refactoring of things and how the request is handled though.

Or I could keep using http-plug / psr-17/ psr-18 things, and see on the discoverable clients how to integrate symfony client (I'd rather do that actually).
enhancement

opened by Taluu 1
Clean json contexts
Merge some contexts so maintaining this would be less of a chore. :}

[x] Add some "each elements in collection" steps

[x] Merge collection / root steps

[x] Merge most positive and negative steps (should ... / should not...)

[x] Merge counts (at least, exact and at most)

~~Merge comparative steps (greater than..., greater or equal..., lower than..., lower or equal...)~~ Not worth it, would complicate it. They were ported into a trait (see next item)

[x] Use traits instead of AbstractJson

[x] Merge Json and AbstractJson contexts
opened by Taluu 1
Remove support for Twig

Fixes #39. The optionnal dependency mess is a mess because Behat and autowiring doesn't really like nullable unloadable dependency if they can't be found, and adding a support for Twig is kinda easy (extend the Rest context, inject your twig and off you go).

opened by Taluu 1
Support namespaces Twig services

Currently, only not-namespaced twig classes are supported (Twig_Environement and not Twig\Environment). Need to fix that... maybe.

Maybe, because I doubt that namespaced twig classes are used, especially as they are only aliases extending the original twig classes.
enhancement wontfix

opened by Taluu 1
Use a real printer for debug

Instead of forcing a format (eg through behapi: { debug: { formatter: 'pretty' } } ), we should use the current printer to print the data correctly, so that it works for all outputs.

opened by Taluu 1
Refactor plugin client builder

As the job was done on the upstream (not yet released though), using the same api makes sense.

I will still need to overwrite it to add the cache capabilities though (creating a plugin client for each request doesn't look optimal, especially for 1000s+ tests)

opened by Taluu 0
JSONPath support

Implement JSONPath support for json context (see https://github.com/SoftCreatR/JSONPath)

To push a bit further would be to support "switching" the fetching of the data from the Json.
enhancement

opened by Taluu 0

Releases(v0.14.0)

v0.14.0(Jan 27, 2021)
A new release with one BC Break, hence the minor version update (as we're on 0.X...), mainly due to the fact that we are now using PSR container and updated to modern versions of php-http.

Changes since 0.13

Add support for PHP8 :tada: (f47070)

Use Shivam Mathur github actions to setup php env (#67)

Use PSR container instead of interop (Ban Behat < 3.7) (#67)

Remove support for some EOLd versions of Symfony (#68, dfb8dd1)

(BC BREAK) Remove the PluginClientBuilder class, as it is now maintained in the PHP-HTTP client-common package (php-http/client-common#158)

Nothing too fancy, mostly cleaning up things. :}
Source code(tar.gz)
Source code(zip)
v0.13.0(Jun 18, 2020)
A new release (plagued ? :D) with some bc breaks, mainly the switch from using httplug to psr interfaces.

Changes since 0.12

Bumped to PHP 7.3 minimum

Switch from phpstan to psalm (#62)

Switch from HttPlug to PSR interfaces (#59)

Removed the Builder trait (#61)

Removed the PhpMatcher context (you can use it yourself)

An example directory has been added, but that is highly experimental : it is used when I tinker Behapi's code, to check I'm not breaking anything else than what I am assuming I am breaking. Some features are failing but that's on purpose.
Source code(tar.gz)
Source code(zip)
v0.12.0(Dec 10, 2018)
This release is mainly a work on contexts. It may contain a BC break or two, as some contexts were "removed", "renamed" or "changed".

This release also uses beberlei's asserts instead of webmozart, because of its builders abilities for assert (Through Assert::that()), it has more assertions than the other one, and it seems to be more maintained too (even though @Nyholm's taken the project now).

Changes (BC Breaks included) since v0.11:

Split some assertions groups into their own traits. They'll probably be on their own context in the future (#52)

Use beberlei/assert instead of webmozart/assert (#53 #38)

Fix the assertion on maxCount (0b999ee16)

Merged most collection / root steps (#52)

Merged most positive / negative assertions (#52)

Removal

BC Break (soft): The Behapi\Json\AbstractContext context is gone and has been merged into Behapi\Json\Context (#52)

Source code(tar.gz)
Source code(zip)