digitalzenworks / api-test
A library for end to end testing web APIs with PHPUnit.
Fund package maintenance!
Requires
- php: ^8.2
- php-http/guzzle7-adapter: ^1.0
- phpunit/phpunit: ^11.0 || ^12.0 || ^13.0
Requires (Dev)
- dealerdirect/phpcodesniffer-composer-installer: *
- php-parallel-lint/php-console-highlighter: ^1.0
- php-parallel-lint/php-parallel-lint: ^1.2.0
- phpcompatibility/php-compatibility: 10.0.0-alpha2
- phpcsstandards/phpcsdevtools: ^1.0
- phpcsstandards/phpcsextra: ^1.2.0
- phpmd/phpmd: ^3.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.1
- phpstan/phpstan-deprecation-rules: ^2.0
- roave/security-advisories: dev-master
- squizlabs/php_codesniffer: ^4.0.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A library for testing web APIs with PHPUnit.
Please ⭐ star this project!
Getting Started
Requirements/dependencies
Use a current security patch release of your PHP version. Local development uses PHP 8.5.12 or later; CI checks PHP 8.2 through 8.5.
-
PHPUnit 11, 12, or 13, selected by Composer for your PHP version.
Installation
Git
git clone https://github.com/jamesjohnmcguire/ApiTest
Composer
composer require --dev digitalzenworks/api-test
Usage
API Testing
APITester sends requests and checks responses with apiEndPointTest().
require_once 'vendor/autoload.php'; use DigitalZenWorks\ApiTest\APITester; use DigitalZenWorks\ApiTest\TestOptions; use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\TestCase; final class ApiTests extends TestCase { #[Test] public function postJson() : void { $apiTester = new APITester('https://httpbin.org'); $options = new TestOptions(); $options->requestDataType = 'json'; $data = [ 'name' => 'Somebody', 'email' => 'Somebody@example.com' ]; $body = $apiTester->apiEndPointTest('POST', '/post', $data, $options); $response = json_decode($body, true); $this->assertIsArray($response); $this->assertEquals($data, $response['json']); } }
The method returns the response body as a string.
| Parameter | Type | Description |
|---|---|---|
| method | string | HTTP method. |
| endPoint | string | Absolute URL or path relative to the configured host. |
| data | array, string, or null | Request data. |
| testOptions | TestOptions | Request options and response assertions. |
TestOptions properties:
| Property | Default | Description |
|---|---|---|
| contentRequired | true | Require nonempty response content. |
| errorExpected | false | Expect an HTTP error; decoded arrays must contain error. |
| guzzleAdditionalOptions | null | Additional Guzzle request options. |
| requestDataType | null | Send data using body, form_params, json, or multipart. |
| tryBasicAsserts | true | Run built-in response assertions. |
| userAgent | Chrome user agent | Value of the User-Agent header. |
Page or End-to-End Testing
PageTester checks HTML responses with webPageTest().
require_once 'vendor/autoload.php'; use DigitalZenWorks\ApiTest\PageTester; use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\TestCase; final class PageTests extends TestCase { #[Test] public function htmlPage() : void { $pageTester = new PageTester('https://httpbin.org', 'text/html', 'text/html'); $content = $pageTester->webPageTest('GET', '/html'); $this->assertStringContainsStringIgnoringCase( '<!DOCTYPE html>', $content); } }
Additional Examples
See Tests/ for more examples.
Additional Notes
Access the Guzzle client through $pageTester->client:
$guzzleClient = $pageTester->client;
Guzzle Response Object
Access the latest response through $pageTester->response:
$response = $pageTester->response; $status = $response->getStatusCode(); $this->assertEquals(200, $status);
Guzzle History Object
Inspect requests, responses, and redirects through $pageTester->history:
$history = $pageTester->history;
Cookies Support
Cookies persist across requests through $pageTester->cookieJar:
$cookieJar = $pageTester->cookieJar;
Details on tryBasicAsserts
With tryBasicAsserts = true, these checks apply:
| Assertion | Condition |
|---|---|
assertNotEmpty($data) |
Content is required. |
assertJson($body) |
JSON is expected, unless an empty body is optional. |
assertEquals(200, $status) |
No HTTP error is expected. |
assertNotEquals(200, $status) |
An HTTP error is expected. |
assertArrayHasKey('error', $data) |
An error is expected and decoded data is an array. |
assertArrayNotHasKey('error', $data) |
No error is expected and decoded data is an array. |
Contributing
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Process:
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Coding style
Please match the current coding style. Most notably:
- One operation per line
- Use complete English words in variable and method names
- Attempt to declare variable and method names in a self-documenting manner
License
Distributed under the MIT License. See LICENSE for more information.
Contact
James John McGuire - @jamesmc - jamesjohnmcguire@gmail.com
Project Link: https://github.com/jamesjohnmcguire/ApiTest