Creating A Custom RestApiContext
In this video we are going to cover ~95% of the code we need to test our API using Behat. The reason we are able to do this - and without us having to write much code at all - is that we will be borrowing the vast majority of the code from an existing Behat extension.
Of course, when taking code from somewhere else, it is important to understand what the code is doing. So for each test step we cover, we will look at the underlying code in the context to make sure we aren't coding blindly.
The good news is that most of our steps are quite repetitive:
- we send in a
GETor aPOSTor aDELETEto a given end point; - we need to log in;
- we need to check the JSON response matches our expectation
And so on. These are common whether we are testing the /users endpoint, or /accounts, or /files, or any other endpoint we create. Most of the time, the general 'shape' of our Behat features follows this pattern.
Also, this is a solved problem. We aren't the first to have a requirement to test an API. Thankfully, others have already done this for us and left behind their code to help us along. Thank you to everyone involved, open source is truly amazing.
Switching to Guzzle
In a previous video we covered how to configure the Behat\MinkExtension.
Well, moving forwards I am removing reliance on MinkExtension ... but we never even used it anyway.
Why?
Well, I was going to try and cover MinkExtension but there is already a ton to cover, and after two separate pieces of member feedback on video length, I concluded that chopping out as much as possible was a better bet than trying to be everything to everyone.
Besides, in the real world PHP we use Guzzle all the time. Interacting with API's is done primarily using Guzzle in almost every project I have used in recent memory, with the exception of one that used Zend HTTP.
It makes sense to 'dog food' our own API during test with the client that most PHP developers will likely use themselves.
The Guzzle config we need is as follows:
# app/config/config_dev.yml
csa_guzzle:
logger: true
clients:
local_test_api:
config:
base_url: http://symfony-rest-example.dev/app_dev.php/And:
# app/config/config_acceptance.yml
csa_guzzle:
logger: true
clients:
local_test_api:
config:
base_url: http://symfony-rest-example.dev/app_acceptance.php/This will allow us to use the same service with a different base_url depending on the environment.
At this stage we won't be using Guzzle outside of our acceptance environment, but sorting out the config is no big deal. If you'd like to know more about configuring Symfony services in this way, be sure to check out the What is a Symfony Service tutorial series here at CodeReviewVideos.
Also, don't forget to enable CSA Guzzle bundle inside your AppKernel.php (3:00 minutes in the video).
Behat WebAPIExtension
Somewhat confusingly, Behat's GitHub repository has two different implementations of a file they call WebApiContext.
There is a WebApiContext in their CommonContexts project, and another WebApiContext in their WebApiExtension project.
At first I wasn't sure which one to go for. I tried both, and the WebApiContext in WebApiExtension proved to be more useful to me.
That said, I don't use the WebApiExtension as a dependency in my project. The reason being that there are some requirements I have that have been sat in a pull request on the WebApiExtension project for as long back as I have been using this code (6 months?) and it has yet to be accepted.
This shouldn't be taken as a criticism - people are busy, and more importantly, they maybe do not want this code in their project. That is their decision.
Instead, I chose to copy their code and use it as the base of my own RestApiContext file. Without further ado, here is my file in full - as it stands currently:
<?php
// /src/AppBundle/Features/Context/RestApiContext.php
namespace AppBundle\Features\Context;
use Behat\Behat\Context\Context;
use Behat\Gherkin\Node\PyStringNode;
use Behat\Gherkin\Node\TableNode;
use Guzzle\Http\Message\Request;
use GuzzleHttp\ClientInterface;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Post\PostFile;
use PHPUnit_Framework_Assert as Assertions;
use Sanpi\Behatch\Json\JsonInspector;
use Sanpi\Behatch\Json\JsonSchema;
/**
* Class RestApiContext
* @package AppBundle\Features\Context
*/
class RestApiContext implements Context
{
/**
* @var string
*/
private $authorization;
/**
* @var ClientInterface
*/
protected $client;
/**
* @var array
*/
private $headers = array();
/**
* @var \GuzzleHttp\Message\RequestInterface
*/
private $request;
/**
* @var \GuzzleHttp\Message\ResponseInterface
*/
private $response;
/**
* @var array
*/
private $placeHolders = array();
/**
* @var string
*/
private $dummyDataPath;
/**
* RestApiContext constructor.
* @param ClientInterface $client
* @param string $dummyDataPath
*/
public function __construct(ClientInterface $client, $dummyDataPath = null)
{
$this->client = $client;
$this->dummyDataPath = $dummyDataPath;
}
/**
* Adds Basic Authentication header to next request.
*
* @param string $username
* @param string $password
*
* @Given /^I am authenticating as "([^"]*)" with "([^"]*)" password$/
*/
public function iAmAuthenticatingAs($username, $password)
{
$this->removeHeader('Authorization');
$this->authorization = base64_encode($username . ':' . $password);
$this->addHeader('Authorization', 'Basic ' . $this->authorization);
}
/**
* Adds JWT Token to Authentication header for next request
*
* @param string $username
* @param string $password
*
* @Given /^I am successfully logged in with username: "([^"]*)", and password: "([^"]*)"$/
*/
public function iAmSuccessfullyLoggedInWithUsernameAndPassword($username, $password)
{
$response = $this->client->post('login', [
'json' => [
'username' => $username,
'password' => $password,
]
]);
\PHPUnit_Framework_Assert::assertEquals(200, $response->getStatusCode());
$responseBody = json_decode($response->getBody(), true);
$this->addHeader('Authorization', 'Bearer ' . $responseBody['token']);
}
/**
* @Given when consuming the endpoint I use the :header of :value
*/
public function whenConsumingTheEndpointIUseTheOf($header, $value)
{
$this->client->setDefaultOption($header, $value);
}
/**
* @When I have forgotten to set the :header
*/
public function iHaveForgottenToSetThe($header)
{
$this->client->setDefaultOption($header, null);
}
/**
* Sets a HTTP Header.
*
* @param string $name header name
* @param string $value header value
*
* @Given /^I set header "([^"]*)" with value "([^"]*)"$/
*/
public function iSetHeaderWithValue($name, $value)
{
$this->addHeader($name, $value);
}
/**
* Sends HTTP request to specific relative URL.
*
* @param string $method request method
* @param string $url relative url
*
* @When /^(?:I )?send a "([A-Z]+)" request to "([^"]+)"$/
*/
public function iSendARequest($method, $url)
{
$url = $this->prepareUrl($url);
$this->request = $this->getClient()->createRequest($method, $url);
if (!empty($this->headers)) {
$this->request->addHeaders($this->headers);
}
$this->sendRequest();
}
/**
* Sends HTTP request to specific URL with field values from Table.
*
* @param string $method request method
* @param string $url relative url
* @param TableNode $post table of post values
*
* @When /^(?:I )?send a ([A-Z]+) request to "([^"]+)" with values:$/
*/
public function iSendARequestWithValues($method, $url, TableNode $post)
{
$url = $this->prepareUrl($url);
$fields = array();
foreach ($post->getRowsHash() as $key => $val) {
$fields[$key] = $this->replacePlaceHolder($val);
}
$bodyOption = array(
'body' => json_encode($fields),
);
$this->request = $this->getClient()->createRequest($method, $url, $bodyOption);
if (!empty($this->headers)) {
$this->request->addHeaders($this->headers);
}
$this->sendRequest();
}
/**
* Sends HTTP request to specific URL with raw body from PyString.
*
* @param string $method request method
* @param string $url relative url
* @param PyStringNode $string request body
*
* @When /^(?:I )?send a "([A-Z]+)" request to "([^"]+)" with body:$/
*/
public function iSendARequestWithBody($method, $url, PyStringNode $string)
{
$url = $this->prepareUrl($url);
$string = $this->replacePlaceHolder(trim($string));
$this->request = $this->getClient()->createRequest(
$method,
$url,
array(
'headers' => $this->getHeaders(),
'body' => $string,
)
);
$this->sendRequest();
}
/**
* Sends HTTP request to specific URL with form data from PyString.
*
* @param string $method request method
* @param string $url relative url
* @param PyStringNode $body request body
*
* @When /^(?:I )?send a "([A-Z]+)" request to "([^"]+)" with form data:$/
*/
public function iSendARequestWithFormData($method, $url, PyStringNode $body)
{
$url = $this->prepareUrl($url);
$body = $this->replacePlaceHolder(trim($body));
$fields = array();
parse_str(implode('&', explode("\n", $body)), $fields);
$this->request = $this->getClient()->createRequest($method, $url);
/** @var \GuzzleHttp\Post\PostBodyInterface $requestBody */
$requestBody = $this->request->getBody();
foreach ($fields as $key => $value) {
$requestBody->setField($key, $value);
}
$this->sendRequest();
}
/**
* @When /^(?:I )?send a multipart "([A-Z]+)" request to "([^"]+)" with form data:$/
*/
public function iSendAMultipartRequestToWithFormData($method, $url, TableNode $post)
{
$url = $this->prepareUrl($url);
$this->request = $this->getClient()->createRequest($method, $url);
$data = $post->getColumnsHash()[0];
$hasFile = false;
if (array_key_exists('filePath', $data)) {
$filePath = $this->dummyDataPath . $data['filePath'];
unset($data['filePath']);
$hasFile = true;
}
/** @var \GuzzleHttp\Post\PostBodyInterface $requestBody */
$requestBody = $this->request->getBody();
foreach ($data as $key => $value) {
$requestBody->setField($key, $value);
}
if ($hasFile) {
$file = fopen($filePath, 'rb');
$postFile = new PostFile('uploadedFile', $file);
$requestBody->addFile($postFile);
}
if (!empty($this->headers)) {
$this->request->addHeaders($this->headers);
}
$this->request->setHeader('Content-Type', 'multipart/form-data');
$this->sendRequest();
}
/**
* Checks that response has specific status code.
*
* @param string $code status code
*
* @Then the response code should :arg1
*/
public function theResponseCodeShouldBe($code)
{
$expected = intval($code);
$actual = intval($this->response->getStatusCode());
Assertions::assertSame($expected, $actual);
}
/**
* Checks that response body contains specific text.
*
* @param string $text
*
* @Then /^(?:the )?response should contain "([^"]*)"$/
*/
public function theResponseShouldContain($text)
{
$expectedRegexp = '/' . preg_quote($text) . '/i';
$actual = (string) $this->response->getBody();
Assertions::assertRegExp($expectedRegexp, $actual);
}
/**
* Checks that response body doesn't contains specific text.
*
* @param string $text
*
* @Then /^(?:the )?response should not contain "([^"]*)"$/
*/
public function theResponseShouldNotContain($text)
{
$expectedRegexp = '/' . preg_quote($text) . '/';
$actual = (string) $this->response->getBody();
Assertions::assertNotRegExp($expectedRegexp, $actual);
}
/**
* Checks that response body contains JSON from PyString.
*
* Do not check that the response body /only/ contains the JSON from PyString,
*
* @param PyStringNode $jsonString
*
* @throws \RuntimeException
*
* @Then /^(?:the )?response should contain json:$/
*/
public function theResponseShouldContainJson(PyStringNode $jsonString)
{
$etalon = json_decode($this->replacePlaceHolder($jsonString->getRaw()), true);
$actual = $this->response->json();
if (null === $etalon) {
throw new \RuntimeException(
"Can not convert etalon to json:\n" . $this->replacePlaceHolder($jsonString->getRaw())
);
}
Assertions::assertGreaterThanOrEqual(count($etalon), count($actual));
foreach ($etalon as $key => $needle) {
Assertions::assertArrayHasKey($key, $actual);
Assertions::assertEquals($etalon[$key], $actual[$key]);
}
}
/**
* Prints last response body.
*
* @Then print response
*/
public function printResponse()
{
$request = $this->request;
$response = $this->response;
echo sprintf(
"%s %s => %d:\n%s",
$request->getMethod(),
$request->getUrl(),
$response->getStatusCode(),
$response->getBody()
);
}
/**
* @Then the response header :header should be equal to :value
*/
public function theResponseHeaderShouldBeEqualTo($header, $value)
{
$header = $this->response->getHeaders()[$header];
Assertions::assertContains($value, $header);
}
/**
* Prepare URL by replacing placeholders and trimming slashes.
*
* @param string $url
*
* @return string
*/
private function prepareUrl($url)
{
return ltrim($this->replacePlaceHolder($url), '/');
}
/**
* Sets place holder for replacement.
*
* you can specify placeholders, which will
* be replaced in URL, request or response body.
*
* @param string $key token name
* @param string $value replace value
*/
public function setPlaceHolder($key, $value)
{
$this->placeHolders[$key] = $value;
}
/**
* @Then the I follow the link in the Location response header
*/
public function theIFollowTheLinkInTheLocationResponseHeader()
{
$location = $this->response->getHeader('Location');
$this->iSendARequest(Request::GET, $location);
}
/**
* @Then the JSON should be valid according to this schema:
*/
public function theJsonShouldBeValidAccordingToThisSchema(PyStringNode $schema)
{
$inspector = new JsonInspector('javascript');
$json = new \Sanpi\Behatch\Json\Json(json_encode($this->response->json()));
$inspector->validate(
$json,
new JsonSchema($schema)
);
}
/**
* Checks, that given JSON node is equal to given value
*
* @Then the JSON node :node should be equal to :text
*/
public function theJsonNodeShouldBeEqualTo($node, $text)
{
$json = new \Sanpi\Behatch\Json\Json(json_encode($this->response->json()));
$inspector = new JsonInspector('javascript');
$actual = $inspector->evaluate($json, $node);
if ($actual != $text) {
throw new \Exception(
sprintf("The node value is '%s'", json_encode($actual))
);
}
}
/**
* Replaces placeholders in provided text.
*
* @param string $string
*
* @return string
*/
protected function replacePlaceHolder($string)
{
foreach ($this->placeHolders as $key => $val) {
$string = str_replace($key, $val, $string);
}
return $string;
}
/**
* Returns headers, that will be used to send requests.
*
* @return array
*/
protected function getHeaders()
{
return $this->headers;
}
/**
* Adds header
*
* @param string $name
* @param string $value
*/
protected function addHeader($name, $value)
{
if (isset($this->headers[$name])) {
if (!is_array($this->headers[$name])) {
$this->headers[$name] = array($this->headers[$name]);
}
$this->headers[$name][] = $value;
} else {
$this->headers[$name] = $value;
}
}
/**
* Removes a header identified by $headerName
*
* @param string $headerName
*/
protected function removeHeader($headerName)
{
if (array_key_exists($headerName, $this->headers)) {
unset($this->headers[$headerName]);
}
}
/**
*
*/
private function sendRequest()
{
try {
$this->response = $this->getClient()->send($this->request);
} catch (RequestException $e) {
$this->response = $e->getResponse();
if (null === $this->response) {
throw $e;
}
}
}
/**
* @return ClientInterface
*/
private function getClient()
{
if (null === $this->client) {
throw new \RuntimeException('Client has not been set in WebApiContext');
}
return $this->client;
}
}This file is a work in progress - there are bits I need to refactor, especially around removing some of the newing up of JSONValidators and such. For now, it does the job.
For reference, this is a few custom functions mixed in with Behat's WebApiExtension WebApiContext and some of the JSON methods from Sanpi's Behatch JSON Context.
As we've covered in a previous video, these steps are used throughout the majority of Behat features we will create during the course of the project.
The above code is a reference and may have changed in future videos / by the end of this tutorial - so be sure to check out the full code repository available once this course is complete, for any logged in site members.
