helpscout/specter-php

JSON API Mocking and Testing for PHP

Specter

Mocking and Testing for PHP Use a single JSON file to generate mock data and as an integration test assertion, _(*1)

Modern development is complicated. This project decouples front end and back end development by providing fixture data and a testing spec with a single file., _(*2)

1. Client and Server teams build a JSON spec file together
2. Mock the endpoint, and have it return that spec file and add the Specter Middleware to convert that spec file into a response filled with random, but sane, data
3. The client team can begin development with this endpoint, and iterate over any changes with the JSON spec. The endpoint delivers real data, and they can set a SpecterSeed header to get repeatable results.
4. The server team can then implement the actual endpoint to meet that spec at their own pace, perhaps in the next sprint. They can use the same spec file to drive an PHPUnit integration test by handing the spec file to the SpecterTestTrait

This lets the teams rapidly create an endpoint specification together, the front end team uses the data from it, and the platform team tests with it., _(*3)

Installation

This is available through composer as helpscout/specter-php., _(*4)

Contributing

1. git clone
2. composer install
3. It will prompt you to please install our commit hooks driven by pre-commit.

Demonstration

Work together among your development teams to spec a new endpoint and create a Specter JSON file that defines your new endpoint. This is a Specter JSON file:, _(*5)

{
  "__specter": "Sample customer record",
  "id": "@randomDigitNotNull@",
  "fname": "@firstName@",
  "lname": "@lastName@",
  "company": "@company@",
  "jobTitle": "@jobTitle@",
  "background": "@catchPhrase@",
  "address": {
    "city": "@city@",
    "state": "@stateAbbr@",
    "zip": "@postcode@",
    "country": "@country@"
  },
  "emails": ["@companyEmail@", "@freeEmail@", "@email@" ]
}

Add a route to return it and use SpecterMiddleware to process it:, _(*6)

$app->get('/api/v1/customer/{id}', function ($request, $response, $args) {
    return $response->withJson(getFixture('customer'));
})->add(new \HelpScout\Specter\SpecterMiddleware);

Receive random data from your endpoint that fulfills the JSON and use it to build out your interface:, _(*7)

{
   "__specter":"Sample customer record",
   "id":6,
   "fname":"Glenda",
   "lname":"Trantow",
   "company":"Kerluke, Rodriguez and Wisoky",
   "jobTitle":"Power Generating Plant Operator",
   "background":"Configurable multi-state standardization",
   "address":{
      "city":"Georgiannachester",
      "state":"TX",
      "zip":"89501",
      "country":"Afghanistan"
   },
   "emails":[
      "dward@friesen.org",
      "nwisozk@gmail.com",
      "juliet.dooley@yahoo.com"
   ]
}

Write a unit test for the endpoint to confirm that it's meeting the spec, and then implement the endpoint for real:, _(*8)

use SpecterTestTrait;

public function testCustomerRouteMeetsSpec()
{
    self::assertResponseContent(
        $this->client->get('/api/v1/customer/37'),
        'customer'
    );
}

Custom Formatters

In addition to the Faker library, Specter provides a few other fomatters that offer some useful mocking., _(*9)

• randomRobotAvatar
• randomGravatar
• relatedElement