API Testing

Testing

Caligrafy Quill 2.26.0. Generated from the source by php qa/build-api-reference.php; the guides explain how to use these classes, this reference says exactly what each public method takes and returns. Back to the API reference.

The base class of the tests of an application (tests/, php caligrafer.php test).

Class	What it is
Caligrafy\Testing\TestCase	Test what the app does through its capabilities, as the pages, REST, the JS client and agents reach them

abstract class Caligrafy\Testing\TestCase

namespace Caligrafy\Testing;

abstract class TestCase extends \PHPUnit\Framework\TestCase

Source: framework/testing/TestCase.php:41

Test what the app does through its capabilities, as the pages, REST, the JS client and agents reach them:

final class BooksTest extends Caligrafy\Testing\TestCase
{
    public function testAReaderAddsABook(): void
    {
        $book = $this->call('create_book', ['title' => 'Dune'], $this->user(1));
        $this->assertSame('Dune', $book['title']);
        $this->assertCapabilityFails('invalid', 'create_book', [], $this->user(1));
        $this->assertCapabilityFails('unauthenticated', 'create_book', ['title' => 'Dune'], 'guest');
        $this->assertStringContainsString('Dune', $this->render('Books/list', ['books' => [$book]]));
    }
}

Each test runs in a database transaction that is rolled back at its end (with DB_ACTIVATE=true), so tests leave the database as they found it; a CREATE, ALTER or DROP ends the transaction (MySQL commits it). Use a database of its own for tests: DB_TEST_DATABASE in .env, or the settings of .env.testing. Bindings of the container, the cache's copies and the query shapes the N+1 warning counts (Query::forgetShapes) are forgotten between tests.

Methods

• ->setUp()
• ->tearDown()
• ->call()
• ->action()
• ->assertCapabilityFails()
• ->user()
• ->render()
• ->fake()
• ->assertQueued()

->setUp()

protected function setUp(): void

No doc comment.

Returns void

Source: framework/testing/TestCase.php:48

->tearDown()

protected function tearDown(): void

No doc comment.

Returns void

Source: framework/testing/TestCase.php:65

->call()

protected function call($capability, array $input = array(), $as = null)

Calls a capability as a channel would, with its permission checks, validation and audit

Parameters

• $capability
• $input array, default array()
• $as Context|object|array|string|null, default null: null: the command line (full access); 'guest'; a user (see user()); or a Context

Returns mixed: its answer

Source: framework/testing/TestCase.php:84

->action()

protected function action($capability, array $input = array(), $as = null)

Calls a webOnly capability as Route::action() does (2.21.0)

Parameters

• $capability
• $input array, default array()
• $as, default null

Returns mixed: its answer: a Caligrafy\Web (describe() says what it answers), or plain data

Source: framework/testing/TestCase.php:93

->assertCapabilityFails()

protected function assertCapabilityFails($kind, $capability, array $input = array(), $as = null)

Asserts that a capability refuses: invalid, unauthenticated, forbidden, not_found or conflict

Parameters

• $kind
• $capability
• $input array, default array()
• $as, default null

Returns ServiceError: the error, to check its message or fields

Source: framework/testing/TestCase.php:104

->user()

protected function user($id = 1, $level = 0, array $attributes = array())

A signed-in user for call(): an id and a permission level (the users column Context::$levelAttribute), plus any other attributes the capability reads

Parameters

• $id, default 1
• $level, default 0
• $attributes array, default array()

Source: framework/testing/TestCase.php:119

->render()

protected function render($view, array $data = array())

The HTML of a Pug view of application/views, as a page would show it

Parameters

• $view
• $data array, default array()

Source: framework/testing/TestCase.php:127

->fake()

protected function fake($id, $object)

Replaces what the container gives for $id (a mailer, a payment gateway) with $object, for this test

Parameters

• $id
• $object

Source: framework/testing/TestCase.php:141

->assertQueued()

protected function assertQueued($capability, ?callable $where = null)

Asserts that a job of this capability was pushed to the queue (in this test), and returns its input

Parameters

• $capability
• $where ?callable, default null

Source: framework/testing/TestCase.php:150