Search by

A library for end to end testing web APIs with PHPUnit.

Package info

github.com/jamesjohnmcguire/ApiTest

Homepage

pkg:composer/digitalzenworks/api-test

Fund package maintenance!

jamesjohnmcguire

Statistics

Installs: 145

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v1.9.44 2026-11-16 04:53 UTC

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.

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:

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Coding style

Please match the current coding style. Most notably:

  1. One operation per line
  2. Use complete English words in variable and method names
  3. 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