{"id":21675935,"url":"https://github.com/helpscout/specter-php","last_synced_at":"2025-06-13T19:36:28.686Z","repository":{"id":62515776,"uuid":"57459094","full_name":"helpscout/specter-php","owner":"helpscout","description":"JSON Mocking and Testing for PHP","archived":false,"fork":false,"pushed_at":"2018-05-03T13:59:42.000Z","size":117,"stargazers_count":18,"open_issues_count":1,"forks_count":0,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-04-12T04:54:58.434Z","etag":null,"topics":["json-spec","laravel-middleware","mocking","php","phpunit","psr-7"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/helpscout.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-30T19:51:40.000Z","updated_at":"2022-01-04T09:52:18.000Z","dependencies_parsed_at":"2022-11-02T10:17:25.879Z","dependency_job_id":null,"html_url":"https://github.com/helpscout/specter-php","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helpscout%2Fspecter-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helpscout%2Fspecter-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helpscout%2Fspecter-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helpscout%2Fspecter-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/helpscout","download_url":"https://codeload.github.com/helpscout/specter-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248519472,"owners_count":21117757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-spec","laravel-middleware","mocking","php","phpunit","psr-7"],"created_at":"2024-11-25T14:11:36.120Z","updated_at":"2025-04-12T04:55:08.383Z","avatar_url":"https://github.com/helpscout.png","language":"PHP","readme":"Specter [![Build Status](https://travis-ci.org/helpscout/specter-php.svg?branch=master)](https://travis-ci.org/helpscout/specter-php) [![Code Climate](https://codeclimate.com/github/helpscout/specter-php/badges/gpa.svg)](https://codeclimate.com/github/helpscout/specter-php) [![Test Coverage](https://codeclimate.com/github/helpscout/specter-php/badges/coverage.svg)](https://codeclimate.com/github/helpscout/specter-php/coverage)\n================================================================================\n\u003e __Mocking and Testing for PHP__\n\u003e Use a single JSON file to generate mock data and as an integration test assertion\n\nModern development is complicated. This project decouples front end and back end\ndevelopment by providing fixture data and a testing spec with a single file.\n\n1. Client and Server teams build [a JSON spec file][spec] together\n2. Mock the endpoint, and have it return that spec file and add the\n   [Specter Middleware][middleware] to convert that spec file into a response\n   filled with random, but sane, data\n3. The client team can begin development with this endpoint, and iterate over\n   any changes with the JSON spec. The endpoint delivers real data, and they\n   can set a `SpecterSeed` header to get repeatable results.\n4. The server team can then implement the actual endpoint to meet that spec at\n   their own pace, perhaps in the next sprint. They can use the **same** spec\n   file to drive an PHPUnit integration test by handing the spec file to the\n   [SpecterTestTrait][testtrait]\n\nThis lets the teams rapidly create an endpoint specification together, the\nfront end team uses the data from it, and the platform team tests with it.\n\n## Installation\n\nThis is available through composer as `helpscout/specter-php`.\n\n## Contributing\n1. `git clone`\n2. `composer install`\n3. It will prompt you to please install our commit hooks driven by\n   [pre-commit][pre-commit].\n\n## Demonstration\n\nWork together among your development teams to spec a new endpoint and create a\nSpecter JSON file that defines your new endpoint. This is a Specter JSON file:\n```json\n{\n  \"__specter\": \"Sample customer record\",\n  \"id\": \"@randomDigitNotNull@\",\n  \"fname\": \"@firstName@\",\n  \"lname\": \"@lastName@\",\n  \"company\": \"@company@\",\n  \"jobTitle\": \"@jobTitle@\",\n  \"background\": \"@catchPhrase@\",\n  \"address\": {\n    \"city\": \"@city@\",\n    \"state\": \"@stateAbbr@\",\n    \"zip\": \"@postcode@\",\n    \"country\": \"@country@\"\n  },\n  \"emails\": [\"@companyEmail@\", \"@freeEmail@\", \"@email@\" ]\n}\n```\n\nAdd a route to return it and use `SpecterMiddleware` to process it:\n```php\n$app-\u003eget('/api/v1/customer/{id}', function ($request, $response, $args) {\n    return $response-\u003ewithJson(getFixture('customer'));\n})-\u003eadd(new \\HelpScout\\Specter\\SpecterMiddleware);\n```\n\nReceive random data from your endpoint that fulfills the JSON and use it to\nbuild out your interface:\n```json\n{\n   \"__specter\":\"Sample customer record\",\n   \"id\":6,\n   \"fname\":\"Glenda\",\n   \"lname\":\"Trantow\",\n   \"company\":\"Kerluke, Rodriguez and Wisoky\",\n   \"jobTitle\":\"Power Generating Plant Operator\",\n   \"background\":\"Configurable multi-state standardization\",\n   \"address\":{\n      \"city\":\"Georgiannachester\",\n      \"state\":\"TX\",\n      \"zip\":\"89501\",\n      \"country\":\"Afghanistan\"\n   },\n   \"emails\":[\n      \"dward@friesen.org\",\n      \"nwisozk@gmail.com\",\n      \"juliet.dooley@yahoo.com\"\n   ]\n}\n```\n\nWrite a unit test for the endpoint to confirm that it's meeting the spec, and\nthen implement the endpoint for real:\n```php\nuse SpecterTestTrait;\n\npublic function testCustomerRouteMeetsSpec()\n{\n    self::assertResponseContent(\n        $this-\u003eclient-\u003eget('/api/v1/customer/37'),\n        'customer'\n    );\n}\n```\n\n## Custom Formatters\n\nIn addition to the Faker library, Specter provides a few\n[other fomatters](https://github.com/helpscout/specter/tree/master/src/Provider)\nthat offer some useful mocking.\n\n* `randomRobotAvatar`\n* `randomGravatar`\n* `relatedElement`\n\n[spec]: https://raw.githubusercontent.com/helpscout/specter/master/tests/fixture/customer.json\n[middleware]: https://github.com/helpscout/specter/blob/master/src/SpecterMiddleware.php\n[testtrait]: https://github.com/helpscout/specter/blob/master/src/SpecterTestTrait.php\n[pre-commit]: http://pre-commit.com/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelpscout%2Fspecter-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhelpscout%2Fspecter-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelpscout%2Fspecter-php/lists"}