Testing¶

The native APIs only work inside Nativella. Elsewhere, in PHPUnit or on the command line, nativella_call() does not exist. Calling an API there throws a Nativella\Exception\RuntimeUnavailableException. Tests swap the client that makes the calls for Nativella\Client\FakeClient.

The fake client¶

Every API class takes a Nativella\Client in its constructor. FakeClient records the calls instead of making them, and answers what the native side would when nothing happens: no file picked, an empty clipboard, a dialog dismissed.

Take a service that exports notes where the user chooses:

use Nativella\Dialog;
use Nativella\Notification;

final readonly class Exporter
{
    public function __construct(
        private Dialog $dialog,
        private Notification $notification,
    ) {
    }

    /**
     * @param list<string> $notes
     */
    public function export(array $notes): void
    {
        $path = $this->dialog->saveFile('Export notes', fileName: 'notes.md');
        if (null === $path) {
            return;
        }

        file_put_contents($path, implode("\n\n", $notes));
        $this->notification->send('Exported', basename($path));
    }
}

Its test drives the dialog with respond(), and checks the notification with calls():

use Nativella\Client\FakeClient;
use Nativella\Dialog;
use Nativella\Notification;
use PHPUnit\Framework\TestCase;

final class ExporterTest extends TestCase
{
    public function testItExportsWhereTheUserChose(): void
    {
        $target = sys_get_temp_dir().'/exporter-test.md';
        $client = new FakeClient();
        $client->respond('dialog.saveFile', ['path' => $target]);

        (new Exporter(new Dialog($client), new Notification($client)))->export(['Groceries', 'Ideas']);

        $this->assertStringEqualsFile($target, "Groceries\n\nIdeas");
        $this->assertSame('Exported', $client->calls('notification.send')[0]->payload['title']);
    }

    public function testNothingHappensWhenTheUserCancels(): void
    {
        // Unless told otherwise, dialog.saveFile answers ['path' => null].
        $client = new FakeClient();

        (new Exporter(new Dialog($client), new Notification($client)))->export(['Groceries']);

        $this->assertSame([], $client->calls('notification.send'));
    }
}

Methods are the native ones, <domain>.<method>: window.open, dialog.confirm, clipboard.readText… The payloads are the JSON objects the API classes send, with camelCase keys. The quickest way to learn them is to make the call and look at $client->calls().

To test how your code handles a failure, queue an exception:

use Nativella\Exception\NativeCallException;

$client->respond('globalShortcut.register', new NativeCallException('globalShortcut.register', new \RuntimeException('Already taken.')));

What it answers by default¶

Without a queued answer, FakeClient returns:

The other methods return nothing (void): they answer an empty result.

With a framework¶

The integrations replace the client in the container, so that the application under test gets a FakeClient wherever it injects an API:

• Symfony: nativella.fake_client: true in the test environment.
• Laravel: see the Laravel page.

Running outside Nativella¶

An application is a web application first, so it also runs with symfony serve, php artisan serve or php -S, in a browser, which is handy for working on templates. The native APIs throw there, so guard the calls that may run outside Nativella:

use Nativella\Nativella;

if ($nativella->isNative()) {
    $window->setTitle($note->title);
}

isNative() of Nativella\Nativella (a service with Symfony, the Nativella facade with Laravel) asks the client. It is true in Nativella and under the fake client, so that the tests go through the native code as the application does. nativella_is_native() in Twig and @native in Blade answer the same. Runtime::isNative() only tells whether nativella_call() exists, which is false in tests, fake client or not, so keep it for where there is no client.