G'day:
Background
I have a real-world requirement to get a small web service written: one that wraps up calls to the getaddress.io UK postcode look-up service. For those not familiar with UK post codes, they look something like "SW1W 0NY" and the chief conceit is that each postcode "generally represents a street, part of a street…". It's very common on an address-filling form for the first step to be trying to use the postcode to return a range of correct addresses, from which the user selects their own. This reduces keying errors or vagueness on their part. We have a few forms in our web apps that hit this webservice, and we need to migrate them over to PHP.
Yesterday I took a stab at implementing this in my own PHP8 project (the one I've been building in my recent articles), and got so focused I forgot to document what I was doing and why. So today I'm revisiting the code again, and writing this thing up. Warning: it's ended up being a monster.
Implementation plan
I need to produce an endpoint along the lines of /postcode-lookup/XX200X, and from the response from that, derive a reliable list of matching addresses to pass to the UI. I'm going to implement this in two parts:
- An adapter to sit in front of / around the HTTP call to the getaddress.io webs service. I mean "adapter" in the sense of the "Adapter Pattern"; I'll build a PHP interface to getaddress.io's HTTP one.
- A controller handler which receives a post-code, calls the adapter, gets a result from it and determines how best to respond to the client based on that result.
There's two approaches I could take with this:
- Top down: start with the interface of my own endpoint, nail that - mocking the adapter to start with - and then move downwards to the adapter and sort out the HTTP calls to getaddress.io.
- Bottom up: start with the HTTP calls to getaddress.io, build and adapter around it, finish that and then create a controller that is driven by how the adapter works.
Either would work. I've chosen the latter for a coupla reasons:
- I wasn't in the mood for dealing with Symfony when I thought about doing this work; I wanted to focus on code, not config.
- I have already documented an exercise in taking the first approach a coupla years ago: Indeed that's a way more thorough handling of the exercise as it handles the front-end integration too.
Not in themselves great reasons to take that approach, but I doubt I would have bothered to do the work had I started with the Symfony side of things (reminding myself how routing, DI and controllers work). I was also only intending to do the adapter part for this exercise, even though I ultimately wired it up to the controller too (and it was dead easy as it turns out).
So. Time for some PHP code, some TDD via good old unit tests.
getaddress.io's web service
I had never used this web service before, but it's straight forward and well documented (again: documentation.getaddress.io). I clearly need an API key to access this thing, so signed-up for one of those (free, very limited usage), but they give some testing postcodes one can use to emulate the various responses one can get from their end point:
These postcodes yield both successful and unsuccessful responses to your request.
- XX2 00X or TR19 7AA or KW1 4YT Returns a 'successful' response
200. Your request was successful.- XX4 00X Returns 'bad request' response
400. Your postcode is not valid.- XX4 01X Returns 'unauthorized' response
401. Your api-key is not valid.- XX4 03X Returns 'forbidden' response
403. Your api-key is valid but you do not have permission to access to the resource.- XX4 29X Returns 'too many requests' response
429. You have made more requests than your allowed limit.- XX5 00X Returns 'server error' response
500. Server error, you should never see this.Request made with these postcodes will not affect your usage.
(ibid.)
Oh, incidentally, they offer far more services than I need to use. I only need to deal with this call: https://api.getAddress.io/find/{postcode}?api-key={API key}.
Adapter
The adapter will need to deal with all those variants in some fashion, and returning the data in PHP rather than JSON; just return a PHP object that reflects success / and relevant failure states, along with a native-PHP representation of the returned address data. It can also through an exception in situations where it couldn't make sense of the response from getaddress.io. As it's only an adapter, it should not be performing any business logic; just interfacing between my app and the getaddress.io service. This is also why it's still returning HTTPish concepts rather than removing that entirely from the mix. That would be the job of a repository/service/some-other-domain-model-object sitting between it and the controller, if I chose to have one. I think an intermediary layer is overkill here, so have not bothered.
Routing and Controller
As mentioned, the public interface to my app needs to be to support GET requests to /postcode-lookup/{postcode}. The controller will be initialised with an adapter instance, the handler method will call its get method, and that will return a Response object, which will have properties for the returned addresses (if any), a message explaining potentially why no addresses were fetchable, and the HTTP status code of the upstream request. Or it - the adapter call - could throw an exception that will also need to be dealt with. The client won't be needing to know about those.
Code
API key
I've added a "missing" integration test here:
public function testEnvironmentVariables($expectedEnvironmentVariable)
{
$this->assertNotFalse(
getenv($expectedEnvironmentVariable),
"Expected environment variable $expectedEnvironmentVariable to exist"
);
}
public function expectedEnvironmentVariablesProvider() : array
{
return [
["MARIADB_HOST"],
["MARIADB_PORT"],
["MARIADB_USER"],
["MARIADB_DATABASE"],
["MARIADB_ROOT_PASSWORD"],
["MARIADB_PASSWORD"],
["ADDRESS_SERVICE_API_KEY"]
];
}
I need all these environment variables to actually exist and be reachable by PHP, so I ought to have an integration test to make sure they do exist. I've added in the ADDRESS_SERVICE_API_KEY on there as this is what I'm about to add, and I want a failing test. You might or might not remember I'm loading my environment variables like this (in docker-compose.yml):
php:
build:
context: php
dockerfile: Dockerfile
env_file:
- envVars.public
- envVars.private
I have two files: the envVars.public one is in source control. It's got stuff like this in it:
MARIADB_HOST=mariadb
MARIADB_PORT=3306
MARIADB_DATABASE=db1
MARIADB_USER=user1
In contrast the envVars.private one is not in source control, as it has stuff like this in it:
# do not commit this file to your repository
MARIADB_ROOT_PASSWORD=[redacted]
MARIADB_PASSWORD=[redacted]
ADDRESS_SERVICE_API_KEY=[redacted]
You can see I've slung the ADDRESS_SERVICE_API_KEY in there. After cycling my containers, that test passes.
Adapter testing
Unit tests
I'm gonna eschew the "lets walk through the TDD steps" here as there's 10 unit tests, two integration tests, and 250 lines of test code that went through a chunk of refactoring after I got it all working. I'm just gonna show the tests - all of them - and discuss them.
/** @testdox It throws an AddressService\Exception if the getaddress.io call returns an unexpected status */
public function testThrowsExceptionOnUnexpectedStatus()
{
$statusToReturn = Response::HTTP_NOT_IMPLEMENTED;
$this->assertCorrectExceptionThrown(
AddressServiceException::class,
"Unexpected status code returned: $statusToReturn"
);
$adapter = $this->getTestAdapter($statusToReturn, "CONTENT_NOT_TESTED");
$adapter->get("POSTCODE_NOT_TESTED");
}
If you refer back to the list of test postcodes above, and the HTTP response statuses they result in, 501 / not implemented is not one of them. So I am testing my handling of this situation throws an exception, because we have NFI what's going on with getaddress.io if we get one of these back from them, so there's no point continuing processing. The relevant fragment of the Adapter code is:
private const SUPPORTED_SERVICE_RESPONSES = [
HttpFoundationResponse::HTTP_OK,
HttpFoundationResponse::HTTP_BAD_REQUEST,
HttpFoundationResponse::HTTP_UNAUTHORIZED,
HttpFoundationResponse::HTTP_FORBIDDEN,
HttpFoundationResponse::HTTP_TOO_MANY_REQUESTS,
HttpFoundationResponse::HTTP_INTERNAL_SERVER_ERROR
];
// ...
if (!in_array($statusCode, self::SUPPORTED_SERVICE_RESPONSES)) {
throw new AddressService\Exception("Unexpected status code returned: $statusCode");
}
Don't worry, I'll list the whole thing further down, I just wanna focus on which bits are being tested for now.
The test code above has a few helper methods I've extracted out during refactor:
private function assertCorrectExceptionThrown(string $type, string $message): void
{
$this->expectException($type);
$this->expectExceptionMessage($message);
}
private function getTestAdapter(int $statusToReturn, string $content): AddressServiceAdapter
{
$client = $this->getMockedClient($statusToReturn, $content);
return new AddressServiceAdapter("NOT_TESTED", $client);
}
private function getMockedClient(int $statusToReturn, string $content): MockObject
{
$response = $this->getMockedResponse($statusToReturn, $content);
$client = $this
->getMockBuilder(HttpClientInterface::class)
->disableOriginalConstructor()
->getMock();
$client
->expects($this->once())
->method("request")
->willReturn($response);
return $client;
}
private function getMockedResponse(int $status, string $content): MockObject
{
$response = $this
->getMockBuilder(ResponseInterface::class)
->disableOriginalConstructor()
->getMock();
$response
->expects($this->atLeastOnce())
->method("getStatusCode")
->willReturn($status);
$response
->expects($this->any())
->method("getContent")
->willReturn($content);
return $response;
}
The strategy here is that I am testing the Adapter's logic, and how it deals with different responses from the HTTP call. So I mock the HTTP client to return the various responses I need to exercise the Adapter logic I need to write. As you'll see from the rest of the tests, they all use the mocked client, and all the exception handling tests use that assertCorrectExceptionThrown custom assertion. This refactoring keeps the tests simple and clear, and just removes necessary boilerplate machinery.
It's just as important to refactor one's tests as it is to refactor one's source code. Test code still needs to be read by humans.
/** @testdox It throws an AddressService\Exception if the body is not JSON */
public function testThrowsExceptionOnBodyNotJson()
{
$this->assertCorrectExceptionThrown(
AddressServiceException::class,
"json_decode returned [Syntax error]"
);
$adapter = $this->getTestAdapter(Response::HTTP_OK, "NOT_JSON");
$adapter->get("NOT_TESTED");
}
You can see how simple this test is, and following the same approach as the previous one. Just testing a slightly different facet of the logic.
And the implementation code for this:
$body = $response->getContent(false);
$lookupResult = json_decode($body, JSON_OBJECT_AS_ARRAY);
if (json_last_error() != JSON_ERROR_NONE) {
throw new AddressService\Exception(
sprintf("json_decode returned [%s]", json_last_error_msg())
);
}
I'll just give you the @testdox line from the other exception-handling tests, followed by the implementation code. The test implementations are all similar: just different return codes and body, so no point reproducing them.
/** @testdox Throws an AddressService\Exception if the body is not an array */
if (!is_array($lookupResult)) {
throw new AddressService\Exception("Response JSON schema is not valid");
}
/** @testdox it throws an AddressService\Exception if there is no address data in the response json */
// …
/** @testdox it throws an AddressService\Exception if the addresses data is not an array */
// …
/** @testdox it throws an AddressService\Exception if the addresses data is not an array of strings */
// …
These three test different subexpressions in the one if expression:
if (
!array_key_exists("addresses", $lookupResult)
|| !is_array($lookupResult["addresses"])
|| count(array_filter($lookupResult["addresses"], fn($address) => !is_string($address)))
) {
throw new AddressService\Exception("Response JSON schema is not valid");
}
I'm not normally crazy about compound if expressions like that, but they're all testing variants of garbage that we don't want to pass back to the calling code.
Those are all the exception-handling tests, now for the situations where we can actually return something:
/** @testdox returns empty addresses with status code on a non-200-OK response */
public function testReturnsEmptyAddressesOnNon200Response()
{
$statusToReturn = Response::HTTP_BAD_REQUEST;
$adapter = $this->getTestAdapter(
$statusToReturn,
'{"Message": "Bad Request: Invalid postcode."}'
);
$result = $adapter->get("NOT_TESTED");
$this->assertEquals($statusToReturn, $result->getHttpStatus());
$this->assertEquals([], $result->getAddresses());
}
// …
/** @testdox it returns the message on a non-200 response */
// …
/** @testdox it returns a standard message if the non-200 response doesn't include a valid one */
// …
These are pretty similar to the exception-handling tests, just different assertions. And the implementation being tested for all of those is in the one function:
private function handleFailureResponse(
array $lookupResult,
int $statusCode
): AddressService\Response {
if (array_key_exists("Message", $lookupResult) && is_string($lookupResult["Message"])) {
return new AddressService\Response([], $statusCode, $lookupResult["Message"]);
}
return new AddressService\Response([], $statusCode, "No failure message returned from service");
}
And finally the happy path:
/** @testdox it returns a Response object if the response is valid */
public function testReturnsResponseObject()
{
$statusToReturn = Response::HTTP_OK;
$expectedAddresses = [
"TEST_ADDRESS_1",
"TEST_ADDRESS_2"
];
$adapter = $this->getTestAdapter(
$statusToReturn,
sprintf('{"addresses": %s}', json_encode($expectedAddresses))
);
$result = $adapter->get("NOT_TESTED");
$this->assertEquals($statusToReturn, $result->getHttpStatus());
$this->assertEquals($expectedAddresses, $result->getAddresses());
}
Implemenation:
private function handleSuccessResponse(array $lookupResult): AddressService\Response
{
if (
!array_key_exists("addresses", $lookupResult)
|| !is_array($lookupResult["addresses"])
|| count(array_filter($lookupResult["addresses"], fn($address) => !is_string($address)))
) {
throw new AddressService\Exception("Response JSON schema is not valid");
}
return new AddressService\Response(
$lookupResult["addresses"],
HttpFoundationResponse::HTTP_OK
);
}
Integration tests
All of these unit tests only test the logic in the Adapter, having mocked-out the HTTP call. They don't actually test it will actually do what it's supposed to, which requires a call to the actual getaddress.io. This is where some integration tests come in.
/** @testdox Tests of the Adapter */
class AdapterTest extends TestCase
{
private $adapter;
protected function setUp(): void
{
$client = HttpClient::create();
$this->adapter = new AddressServiceAdapter(getenv("ADDRESS_SERVICE_API_KEY"), $client);
}
/** @testdox It can get addresses from a valid postcode */
public function testCanGetAddress()
{
$response = $this->adapter->get(TestConstants::POSTCODE_OK);
$this->assertEquals(Response::HTTP_OK, $response->getHttpStatus());
$this->assertGreaterThanOrEqual(1, count($response->getAddresses()));
$this->assertEmpty($response->getMessage());
}
public function provideErrorTestCases(): array
{
return [
[TestConstants::POSTCODE_INVALID, Response::HTTP_BAD_REQUEST],
[TestConstants::POSTCODE_UNAUTHORIZED, Response::HTTP_UNAUTHORIZED],
[TestConstants::POSTCODE_FORBIDDEN, Response::HTTP_FORBIDDEN],
[TestConstants::POSTCODE_OVER_LIMIT, Response::HTTP_TOO_MANY_REQUESTS],
[TestConstants::POSTCODE_SERVER_ERROR, Response::HTTP_INTERNAL_SERVER_ERROR]
];
}
/**
* @testdox It returns the expected HTTP status code and a message but no addresses on an error
* @dataProvider provideErrorTestCases
*/
public function testReturnsExpectedHttpStatusAndMessageButNoAddressesOnError($postcode, $expectedHttpStatus)
{
$response = $this->adapter->get($postcode);
$this->assertEquals($expectedHttpStatus, $response->getHttpStatus());
$this->assertNotEmpty($response->getMessage());
$this->assertEquals(0, count($response->getAddresses()));
}
}
These test a happy-path response, as well as how the other "failure" responses from getaddress.io are handled. One might wonder why I don't test the "utter failure" cases here, where I throw an exception. I almost did, but then I thought that's nothing to do with the integration with getaddress.io, it's all down to how I handle that integration, and that's my code, and covered in the unit tests.
The only interesting / non-standard thing in that lot is the code to get the API key:
$this->adapter = new AddressServiceAdapter(getenv("ADDRESS_SERVICE_API_KEY"), $client);
The app never needs to know the key. Just the environment does.
Oh this code references some TestConstants:
<?php
namespace adamcameron\php8\tests\Fixtures\AddressService;
class TestConstants
{
// provided by https://documentation.getaddress.io/ (these do not impact look-up usage)
public const POSTCODE_OK = "XX2 00X";
public const POSTCODE_INVALID = "XX4 00X";
public const POSTCODE_UNAUTHORIZED = "XX4 01X";
public const POSTCODE_FORBIDDEN = "XX4 03X";
public const POSTCODE_OVER_LIMIT = "XX4 29X";
public const POSTCODE_SERVER_ERROR = "XX5 00X";
}
These are separate from the integration test class as the controller tests need them too. I'll get to that.
Adapter implementation
namespace adamcameron\php8\Adapter\AddressService;
use adamcameron\php8\Adapter\AddressService;
use Symfony\Component\HttpFoundation\Response as HttpFoundationResponse;
use Symfony\Contracts\HttpClient\HttpClientInterface;
use Symfony\Contracts\HttpClient\ResponseInterface;
class Adapter
{
These are the details we need from getaddress.io:
private const SUPPORTED_SERVICE_RESPONSES = [
HttpFoundationResponse::HTTP_OK,
HttpFoundationResponse::HTTP_BAD_REQUEST,
HttpFoundationResponse::HTTP_UNAUTHORIZED,
HttpFoundationResponse::HTTP_FORBIDDEN,
HttpFoundationResponse::HTTP_TOO_MANY_REQUESTS,
HttpFoundationResponse::HTTP_INTERNAL_SERVER_ERROR
];
private const SERVICE_URL_TEMPLATE = "https://api.getAddress.io/find/{postcode}?api-key={api-key}";
private string $apiKey;
private HttpClientInterface $client;
public function __construct(string $apiKey, HttpClientInterface $client)
{
$this->apiKey = $apiKey;
$this->client = $client;
}
This is the only public functions in here:
public function get(string $postCode) : AddressService\Response
{
$response = $this->makeRequest($postCode);
$lookupResult = $this->extractValidLookupResult($response);
return $this->handleValidatedResponse($response, $lookupResult);
}
Everything else is just refactoring to keep each task (ie: function) separate:
private function makeRequest(string $postCode): ResponseInterface
{
$url = strtr(
self::SERVICE_URL_TEMPLATE,
["{postcode}" => $postCode, "{api-key}" => $this->apiKey]
);
return $this->client->request("GET", $url);
}
private function extractValidLookupResult(ResponseInterface $response): array
{
$statusCode = $response->getStatusCode();
if (!in_array($statusCode, self::SUPPORTED_SERVICE_RESPONSES)) {
throw new AddressService\Exception("Unexpected status code returned: $statusCode");
}
$body = $response->getContent(false);
$lookupResult = json_decode($body, JSON_OBJECT_AS_ARRAY);
if (json_last_error() != JSON_ERROR_NONE) {
throw new AddressService\Exception(
sprintf("json_decode returned [%s]", json_last_error_msg())
);
}
if (!is_array($lookupResult)) {
throw new AddressService\Exception("Response JSON schema is not valid");
}
return $lookupResult;
}
private function handleValidatedResponse(
ResponseInterface $response,
array $lookupResult
): AddressService\Response {
$statusCode = $response->getStatusCode();
if ($statusCode == HttpFoundationResponse::HTTP_OK) {
return $this->handleSuccessResponse($lookupResult);
}
return $this->handleFailureResponse($lookupResult, $statusCode);
}
private function handleSuccessResponse(array $lookupResult): AddressService\Response
{
if (
!array_key_exists("addresses", $lookupResult)
|| !is_array($lookupResult["addresses"])
|| count(array_filter($lookupResult["addresses"], fn($address) => !is_string($address)))
) {
throw new AddressService\Exception("Response JSON schema is not valid");
}
return new AddressService\Response(
$lookupResult["addresses"],
HttpFoundationResponse::HTTP_OK
);
}
private function handleFailureResponse(
array $lookupResult,
int $statusCode
): AddressService\Response {
if (array_key_exists("Message", $lookupResult) && is_string($lookupResult["Message"])) {
return new AddressService\Response([], $statusCode, $lookupResult["Message"]);
}
return new AddressService\Response([], $statusCode, "No failure message returned from service");
}
}
Hopefully given the explanations of all that in the tests, that's all clear. The code is pretty straight forward.
I'm using a custom exception so any consuming code can seprate out out "stuff this Adapter might throw" from "anything else that went wrong" (say for example the Symfony HttpClient spat the dummy for some reason):
namespace adamcameron\php8\Adapter\AddressService;
class Exception extends \RuntimeException
{
}
I will get murderous looks from some ppl for having a class that only holds a coupla data points and some accessors for same, but the adapter does simply return data, but it's a specific sort of data, and the consuming code ought only be reading it, not writing it. I think this is legit usage:
namespace adamcameron\php8\Adapter\AddressService;
class Response
{
private array $addresses;
private int $httpStatus;
private string $message;
public function __construct(array $addresses, int $httpStatus, string $message = "")
{
$this->addresses = $addresses;
$this->httpStatus = $httpStatus;
$this->message = $message;
}
public function getAddresses()
{
return $this->addresses;
}
public function getHttpStatus()
{
return $this->httpStatus;
}
public function getMessage()
{
return $this->message;
}
}
If PHP allowed it, I'd probably make this an inner class of the Adapter as well. But PHP can't so just having it in the same package will have to do. I realise PHP now allows for class expressions, or anonymous classes or whatever they are, but I don't think that's quite right for this application. I just need to return an object from the adapter for the calling code to get predictable / save / checked values from.
Controller integration
I cheated with this bit and did not TDD it. I could not remember how controllers in Symfony worked, so I got the controller operational first, and then backfilled the tests. Soz.
Routing and service config
Firstly the routing (in routes.yaml):
controllers:
resource:
path: ../src/Controller/
namespace: adamcameron\php8\Controller
type: attribute
PostcodeLookup:
path: /postcode-lookup/{postcode}
controller: adamcameron\php8\Controller\PostcodeLookupController::doGet
methods: GET
Then some DI config (in services.yaml):
# …
adamcameron\php8\Adapter\AddressService\Adapter:
public: true
arguments:
$apiKey: '%env(ADDRESS_SERVICE_API_KEY)%'
$client: '@Symfony\Component\HttpClient\HttpClient'
Symfony\Component\HttpClient\HttpClient:
factory: ['\Symfony\Component\HttpClient\HttpClient','create']
# …
I only need to put the services that have non-obvious constructor argument requirements, like how I need to specify to use the environment variable for its $apiKey argument, and I need to specify to use the HttpClient::create factory method to create the $client value. Everything else is auto-wired on the basis of the type in the constructor's method signature.
Accordingly, the controller will be taking an instance of the Adapter, but Symfony can work that out from the type specification in its constructor method signature, and know to get the one I have configured here. Dead clever.
Controller implementation
namespace adamcameron\php8\Controller;
use adamcameron\php8\Adapter\AddressService\Adapter as AddressServiceAdapter;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Response;
class PostcodeLookupController extends AbstractController
{
private AddressServiceAdapter $addressServiceAdapter;
public function __construct(AddressServiceAdapter $addressServiceAdapter)
{
$this->addressServiceAdapter = $addressServiceAdapter;
}
public function doGet(string $postcode)
{
try {
$response = $this->addressServiceAdapter->get($postcode);
return new JsonResponse(
[
'postcode' => $postcode,
'addresses' => $response->getAddresses(),
'message' => $response->getMessage()
],
$response->getHttpStatus()
);
} catch (\Exception $e) {
return new JsonResponse(
[
'postcode' => $postcode,
'addresses' => [],
'message' => $e->getMessage()
],
Response::HTTP_INTERNAL_SERVER_ERROR
);
}
}
}
As all good controller methods ought to be: simple. It receives a value from the request… passes it to the model tier to get some data… based on vagaries of the data, works out how to build the response… and sends it.
Here the conceit is that I really don't care what exceptions the Adapter might throw: I don't want to break the response, so I just swallow them and return an emptyish response, with the appropriate server error.
Controller testing
These are all in PostcodeLookupControllerTest.
private KernelBrowser $client;
protected function setUp(): void
{
$this->client = static::createClient();
}
/** @testdox It retrieves addresses when the post code is valid */
public function testRetrievesAddressesWhenPostCodeIsValid()
{
$this->client->request(
"GET",
sprintf("/postcode-lookup/%s", TestConstants::POSTCODE_OK)
);
$response = $this->client->getResponse();
$this->assertEquals(
Response::HTTP_OK,
$response->getStatusCode()
);
$result = json_decode($response->getContent(), false);
$this->assertObjectHasAttribute('addresses', $result);
$this->assertGreaterThanOrEqual(1, count($result->addresses));
}
Happy path: it returns addresses. Hurrah. I don't check the contents of the addresses as I am happy that the Adapter code will only let legit ones through, and the content of the addresses is outwith my control: that's on getaddress.io.
/**
* @testdox It returns an error status code and no addresses when the postcode is invalid
* @dataProvider provideCasesForClientErrorTests
*/
public function testReturnsErrorStatusCodeAndNoAddressesWhenPostCodeIsInvalid(
string $postcode,
int $statusCode
) {
$this->client->request(
"GET",
sprintf("/postcode-lookup/%s", $postcode)
);
$response = $this->client->getResponse();
$this->assertEquals($statusCode, $response->getStatusCode());
$result = json_decode($response->getContent(), false);
$this->assertObjectHasAttribute('addresses', $result);
$this->assertEmpty($result->addresses);
}
public function provideCasesForClientErrorTests() : array
{
return [
[TestConstants::POSTCODE_INVALID, Response::HTTP_BAD_REQUEST],
[TestConstants::POSTCODE_UNAUTHORIZED, Response::HTTP_UNAUTHORIZED],
[TestConstants::POSTCODE_FORBIDDEN, Response::HTTP_FORBIDDEN],
[TestConstants::POSTCODE_OVER_LIMIT, Response::HTTP_TOO_MANY_REQUESTS],
[TestConstants::POSTCODE_SERVER_ERROR, Response::HTTP_INTERNAL_SERVER_ERROR]
];
}
Superficial tests of all the expected failure situations, making sure they "work".
This next one is more interesting:
/** @testdox it returns an error status and no addresses when there's been a server error */
public function testReturnsErrorStatusCodeAndNoAddressesWhenServerError()
{
$container = self::getContainer();
$mockedAddressServiceAdapter = $this
->getMockBuilder(AddressService\Adapter::class)
->disableOriginalConstructor()
->onlyMethods(['get'])
->getMock();
$mockedAddressServiceAdapter
->expects($this->once())
->method('get')
->willThrowException(new AddressService\Exception("TEST_ERROR_MESSAGE"));
$container->set(AddressService\Adapter::class, $mockedAddressServiceAdapter);
$this->client->request(
"GET",
sprintf("/postcode-lookup/%s", TestConstants::POSTCODE_OK)
);
$response = $this->client->getResponse();
$this->assertEquals(
Response::HTTP_INTERNAL_SERVER_ERROR,
$response->getStatusCode()
);
$result = json_decode($response->getContent(), false);
$this->assertObjectHasAttribute('addresses', $result);
$this->assertEmpty($result->addresses);
$this->assertEquals("TEST_ERROR_MESSAGE", $result->message);
}
Here I'm mocking the dependency injection container to mock-out the HttpClient to fake a server error on "their" end. It's good to know how to do that, and it's fairly straight forward (he says, after googling for over an hour to find out how to do it!). I'm actually thinking now that this is a functional test, not an integration test, as it's not actually hitting the external service. Hrm. I shall move it I think. Oh: I think "functional test" not "unit test" because it's cutting across a couple of concerns: Adapter logic and Controller logic, and that's where I make the (admittedly fairly arbitrary) distinction: if the "unit" is in one object: unit test. If it goes across one object into a dependent object: functional test.
I'm pretty sure that's it. Just as well. This is a monster of an article. Sorry.
Conclusions, and "next…"
I need to improve this by paying attention to a couple of those statuses back from getaddress.io, namely the 401, 403 and 429 responses. These might need remediation on our end, so I want to log something if we get those responses. And also log something in the "catch all" catch there. If there's been an unexpected error, whilst the client might not care, we should.
I'm gonna need to mess around with Monolog to do that, so I'll take that as a separate refresher exercise.
Well done, if you got this far. All the code for this is in the 1.7.3 tag on GitHub (I've linked everything relevant directly as well).
Righto.
--
Adam
