create-prisma-php-app 5.1.0-alpha.3 → 5.1.0-alpha.30

package/dist/tests/README.md

@@ -0,0 +1,119 @@
+# App tests
+
+PHPUnit tests for the **application** code — `src/Lib/**`, the app's wire
+contracts, and `src/Lib/Websocket/sockets.php` registrations — not the Prisma
+PHP framework under `vendor/tsnc/prisma-php` (that package carries its own
+suite in its source repo).
+
+## The command
+
+```bash
+npm run test
+```
+
+That runs PHPUnit through `settings/run-tests.ts`, which uses the PHP binary
+from `prisma-php.json` (`phpRootPathExe`) so the suite runs with the same PHP
+the app runs on. It exits non-zero on any failure, so CI, a pre-commit hook,
+or an agent knows exactly when something broke.
+
+Narrow a run with PHPUnit's own flags after `--`:
+
+```bash
+npm run test -- --filter CsrfTest
+npm run test -- --filter testValidTokenRoundTrip
+```
+
+Running PHPUnit directly also works: `php vendor/phpunit/phpunit/phpunit`
+(configuration is picked up from `phpunit.xml` at the project root).
+
+## Layout
+
+One file per surface, flat in `tests/`:
+
+| File | Surface |
+| --- | --- |
+| `bootstrap.php` | Shared setup: autoloader, path constants, deterministic test env |
+| `Support/` | Reusable fakes (`Tests\Support\...`, autoloaded via composer `autoload-dev`) |
+| `Support/Features.php` | Feature flags read from `prisma-php.json` |
+| `Support/RequiresFeature.php` | Skip guard for tests of optional features |
+| `FeaturesTest.php` | The suite's own feature awareness mirrors `prisma-php.json` |
+| `CsrfTest.php` | The `pp_csrf` cookie family and `X-CSRF-Token` validation |
+| `RpcWireContractTest.php` | PulsePoint wire headers (`$isRpc` / `$isNavigation` / `$isWire`), including the pin that the legacy header stays dead |
+| `DeferComponentRootsTest.php` | Server-deferred component roots: outermost `[pp-component]` body roots ship inside inert `<template pp-component>` wrappers |
+| `SocketTest.php` | One socket connection: JSON frames, reserved error shape, close semantics |
+| `SocketRegistryTest.php` | Named-socket registration and duplicate refusal |
+| `SocketPoolTest.php` | Broadcast and pruning |
+| `ConnectionManagerTest.php` | The full named-socket wire: handshake refusals, argument frame, auth, limits |
+| `SocketsRegistrationTest.php` | The app's real `sockets.php` loads and names its sockets |
+| `AuthTest.php` | JWT round trip, tamper/expiry/foreign-secret rejection |
+
+## The test environment is deterministic
+
+`tests/bootstrap.php` does **not** load the real `.env`. It loads the composer
+autoloader plus `settings/paths.php`, then sets deterministic defaults
+(`APP_ENV=development`, a 32-byte `AUTH_SECRET`, `FUNCTION_CALL_SECRET`) only
+when the variable is not already set — so the suite behaves the same on any
+machine, never depends on real secrets, and CI can still override. The Prisma
+PHP `bootstrap.php` at the project root (route resolution, rendering, CSRF
+cookie issuing) is **not** booted; tests exercise app classes directly.
+
+A test that needs a different env value must set it with `putenv(...)` and
+restore the previous value in `tearDown()` (`PP\Env` reads `getenv()` first) —
+see `ConnectionManagerTest::setEnv()` for the pattern.
+
+## Optional features are optional in the suite too
+
+`prisma-php.json` decides which optional scaffolds exist (`websocket`, `mcp`,
+`swaggerDocs`, `prisma`, ...). A test for an optional feature must guard on
+the flag, or a freshly generated app without that feature fatals instead of
+passing:
+
+```php
+use Tests\Support\RequiresFeature;
+
+final class MySocketTest extends TestCase
+{
+    use RequiresFeature;
+
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket'); // FIRST line, before touching the scaffold
+    }
+}
+```
+
+When the flag is off the test reports itself as skipped with the reason and
+the enable command — never as a failure. `tearDown()` still runs after a
+skip, so teardown code must not assume the feature's classes exist (see
+`SocketRegistryTest::resetRegistry()` for the `class_exists` guard).
+
+The websocket suites (`SocketTest`, `SocketRegistryTest`, `SocketPoolTest`,
+`ConnectionManagerTest`, `SocketsRegistrationTest`) are gated this way. Core
+surfaces — CSRF, the RPC wire headers, auth — are always-on and never gated.
+
+## Conventions
+
+- one `SomethingTest.php` per surface, in the `Tests` namespace; shared fakes
+  live in `tests/Support` under `Tests\Support`
+- static registries (`SocketRegistry`) are reset in `setUp()`/`tearDown()` via
+  reflection so tests never depend on each other's order
+- superglobals a test touches (`$_SERVER`, `$_COOKIE`, env) are backed up in
+  `setUp()` and restored in `tearDown()`
+- wire tests assert **frames and close codes**, not internals:
+  `Tests\Support\FakeConnection` records everything the server sends, so a
+  test reads the conversation the browser would have seen
+- expected framework failures are part of the contract — a refusal test
+  asserts the readable `{"error": "..."}` frame (or HTTP status), not just
+  "something failed"
+- tests cover app-level code and the wire contracts the app depends on; do
+  not test Prisma PHP internals from here — those belong to the package
+  repo's own suite (`vendor/tsnc/prisma-php/tests` when vendored)
+
+## For AI agents
+
+Read this file plus `node_modules/prisma-php/dist/docs/testing.md` before
+adding or changing tests. When you add an app feature with logic worth
+protecting — an exposed function's validation, a socket handler, an auth
+rule — add the matching `*Test.php` here in the same change, and run
+`npm run test` before declaring the work done. A red suite is a finding to
+fix, not to silence.

package/dist/tests/RpcWireContractTest.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\TestCase;
+use PP\Request;
+
+/**
+ * The PulsePoint wire headers, as the app depends on them.
+ *
+ * `pp.rpc(...)` posts with `X-PP-RPC: true` + `X-PP-Function`; SPA navigation
+ * fetches with `X-PP-Navigation: true`; both carry `X-PulsePoint-Wire: true`.
+ * This is a complete migration — the legacy `PP-Wire-Request` header must NOT
+ * be recognized any more, and that is pinned here on purpose.
+ */
+final class RpcWireContractTest extends TestCase
+{
+    private array $serverBackup = [];
+
+    protected function setUp(): void
+    {
+        $this->serverBackup = $_SERVER;
+    }
+
+    protected function tearDown(): void
+    {
+        $_SERVER = $this->serverBackup;
+    }
+
+    private function initRequest(array $server): void
+    {
+        $_SERVER = array_merge([
+            'HTTP_HOST' => 'example.test',
+            'SCRIPT_NAME' => '/index.php',
+            'REMOTE_ADDR' => '127.0.0.1',
+        ], $server);
+
+        Request::init();
+    }
+
+    public function testRpcPostIsDetected(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'POST',
+            'CONTENT_TYPE' => 'application/json',
+            'HTTP_X_PULSEPOINT_WIRE' => 'true',
+            'HTTP_X_PP_RPC' => 'true',
+            'HTTP_X_PP_FUNCTION' => 'saveProfile',
+        ]);
+
+        self::assertTrue(Request::$isWire);
+        self::assertTrue(Request::$isRpc);
+        self::assertFalse(Request::$isNavigation);
+    }
+
+    public function testNavigationGetIsWireButNotRpc(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'GET',
+            'HTTP_X_PULSEPOINT_WIRE' => 'true',
+            'HTTP_X_PP_NAVIGATION' => 'true',
+        ]);
+
+        self::assertTrue(Request::$isWire);
+        self::assertFalse(Request::$isRpc);
+        self::assertTrue(Request::$isNavigation);
+    }
+
+    public function testRpcHeaderOnAGetIsNotAnRpc(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'GET',
+            'HTTP_X_PP_RPC' => 'true',
+        ]);
+
+        self::assertFalse(Request::$isRpc);
+    }
+
+    public function testPlainRequestCarriesNoWireFlags(): void
+    {
+        $this->initRequest(['REQUEST_METHOD' => 'GET']);
+
+        self::assertFalse(Request::$isWire);
+        self::assertFalse(Request::$isRpc);
+        self::assertFalse(Request::$isNavigation);
+    }
+
+    public function testLegacyWireHeaderIsNoLongerRecognized(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'POST',
+            'CONTENT_TYPE' => 'application/json',
+            'HTTP_PP_WIRE_REQUEST' => 'true',
+        ]);
+
+        self::assertFalse(Request::$isWire, 'complete migration: no legacy header support');
+        self::assertFalse(Request::$isRpc);
+    }
+}

package/dist/tests/SocketPoolTest.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use Lib\Websocket\Socket;
+use Lib\Websocket\SocketPool;
+use PHPUnit\Framework\TestCase;
+use Tests\Support\FakeConnection;
+use Tests\Support\RequiresFeature;
+
+/**
+ * A broadcast pool: one value to everyone, with gone connections pruned on
+ * the way.
+ */
+final class SocketPoolTest extends TestCase
+{
+    use RequiresFeature;
+
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+    }
+
+    public function testBroadcastReachesEveryOpenSocket(): void
+    {
+        $pool = new SocketPool();
+        $connA = new FakeConnection();
+        $connB = new FakeConnection();
+
+        $pool->add(new Socket($connA, 'chat'));
+        $pool->add(new Socket($connB, 'chat'));
+
+        $pool->broadcast(['text' => 'hello room']);
+
+        self::assertSame([['text' => 'hello room']], $connA->sentFrames);
+        self::assertSame([['text' => 'hello room']], $connB->sentFrames);
+    }
+
+    public function testClosedSocketsArePrunedByBroadcast(): void
+    {
+        $pool = new SocketPool();
+        $connA = new FakeConnection();
+        $gone = new Socket(new FakeConnection(), 'chat');
+
+        $pool->add(new Socket($connA, 'chat'));
+        $pool->add($gone);
+        $gone->handleClose();
+
+        $pool->broadcast('first');
+
+        self::assertSame(1, $pool->count(), 'the closed connection was forgotten');
+        self::assertSame(['first'], $connA->sentFrames);
+    }
+
+    public function testDiscardRemovesOnlyThatSocket(): void
+    {
+        $pool = new SocketPool();
+        $keep = new Socket(new FakeConnection(), 'chat');
+        $drop = new Socket(new FakeConnection(), 'chat');
+
+        $pool->add($keep);
+        $pool->add($drop);
+        $pool->discard($drop);
+
+        self::assertSame(1, $pool->count());
+    }
+}

package/dist/tests/SocketRegistryTest.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use InvalidArgumentException;
+use Lib\Websocket\SocketRegistry;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use Tests\Support\RequiresFeature;
+
+/**
+ * The named-socket registry: names are the whole address, so they are unique
+ * application-wide and a duplicate is refused at registration time.
+ */
+final class SocketRegistryTest extends TestCase
+{
+    use RequiresFeature;
+
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+        self::resetRegistry();
+    }
+
+    protected function tearDown(): void
+    {
+        self::resetRegistry();
+    }
+
+    public static function resetRegistry(): void
+    {
+        // tearDown() still runs after a feature skip, and in an app without
+        // the websocket scaffold the class does not exist — nothing to reset.
+        if (!class_exists(SocketRegistry::class)) {
+            return;
+        }
+
+        $reflection = new ReflectionClass(SocketRegistry::class);
+        $reflection->getProperty('sockets')->setValue(null, []);
+    }
+
+    public function testRegisterAndResolveByName(): void
+    {
+        $handler = static function (): void {};
+
+        SocketRegistry::register('chat', $handler, requireAuth: true, allowedRoles: ['admin']);
+
+        $entry = SocketRegistry::get('chat');
+        self::assertNotNull($entry);
+        self::assertSame('chat', $entry['name']);
+        self::assertSame($handler, $entry['handler']);
+        self::assertTrue($entry['requireAuth']);
+        self::assertSame(['admin'], $entry['allowedRoles']);
+        self::assertSame(['chat'], SocketRegistry::names());
+    }
+
+    public function testUnknownNameResolvesToNull(): void
+    {
+        self::assertNull(SocketRegistry::get('nope'));
+    }
+
+    public function testDuplicateNameIsRefused(): void
+    {
+        SocketRegistry::register('chat', static function (): void {});
+
+        $this->expectException(InvalidArgumentException::class);
+        SocketRegistry::register('chat', static function (): void {});
+    }
+
+    public function testEmptyNameIsRefused(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        SocketRegistry::register('', static function (): void {});
+    }
+}

package/dist/tests/SocketTest.php

@@ -0,0 +1,124 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use InvalidArgumentException;
+use Lib\Websocket\Socket;
+use PHPUnit\Framework\TestCase;
+use Tests\Support\FakeConnection;
+use Tests\Support\RequiresFeature;
+
+/**
+ * One open connection, as a socket handler holds it: JSON frames out, the
+ * reserved `{"error": ...}` shape refused, and close semantics.
+ */
+final class SocketTest extends TestCase
+{
+    use RequiresFeature;
+
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+    }
+
+    public function testSendEncodesOneJsonValuePerFrame(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+
+        self::assertTrue($socket->send(['text' => 'hello']));
+        self::assertTrue($socket->send('plain'));
+        self::assertTrue($socket->send(42));
+
+        self::assertSame([['text' => 'hello'], 'plain', 42], $conn->sentFrames);
+    }
+
+    public function testSendRefusesTheReservedErrorShape(): void
+    {
+        $socket = new Socket(new FakeConnection(), 'echo');
+
+        $this->expectException(InvalidArgumentException::class);
+        $socket->send(['error' => 'looks like a failure frame']);
+    }
+
+    public function testAPayloadThatMerelyContainsAnErrorKeyIsSendable(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+
+        self::assertTrue($socket->send(['error' => 'mine', 'other' => 1]));
+        self::assertSame(['error' => 'mine', 'other' => 1], $conn->lastFrame());
+    }
+
+    public function testSendAfterCloseReturnsFalse(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+
+        $socket->handleClose();
+
+        self::assertFalse($socket->send('late'));
+        self::assertSame([], $conn->sentFrames);
+    }
+
+    public function testMessageListenerReceivesDecodedValues(): void
+    {
+        $socket = new Socket(new FakeConnection(), 'echo');
+
+        $seen = [];
+        $socket->onMessage(function (mixed $value) use (&$seen): void {
+            $seen[] = $value;
+        });
+
+        $socket->handleMessage(['text' => 'hi']);
+        $socket->handleMessage('plain');
+
+        self::assertSame([['text' => 'hi'], 'plain'], $seen);
+    }
+
+    public function testCloseListenerFiresExactlyOnce(): void
+    {
+        $socket = new Socket(new FakeConnection(), 'echo');
+
+        $closes = 0;
+        $socket->onClose(function () use (&$closes): void {
+            $closes++;
+        });
+
+        $socket->handleClose();
+        $socket->handleClose();
+
+        self::assertSame(1, $closes);
+        self::assertFalse($socket->isOpen());
+    }
+
+    public function testErrorSendsTheReservedFrameThenCloses(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+
+        $socket->error('no such room');
+
+        self::assertSame(['error' => 'no such room'], $conn->lastFrame());
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testCloseUsesNormalClosure(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+
+        $socket->close();
+
+        self::assertSame([1000], $conn->closeCodes);
+    }
+
+    public function testPayloadIsHandedToTheHandler(): void
+    {
+        $socket = new Socket(new FakeConnection(), 'echo', ['role' => 'admin']);
+
+        self::assertSame(['role' => 'admin'], $socket->payload());
+    }
+}

package/dist/tests/SocketsRegistrationTest.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use Lib\Websocket\SocketRegistry;
+use PHPUnit\Framework\TestCase;
+use Tests\Support\RequiresFeature;
+
+/**
+ * The app's real registration file loads cleanly and registers every socket
+ * the frontend connects to. A socket the browser names but the server never
+ * registered is a refused connection in production — catch it here instead.
+ */
+final class SocketsRegistrationTest extends TestCase
+{
+    use RequiresFeature;
+
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+        SocketRegistryTest::resetRegistry();
+    }
+
+    protected function tearDown(): void
+    {
+        SocketRegistryTest::resetRegistry();
+    }
+
+    public function testTheRegistrationFileLoadsAndNamesItsSockets(): void
+    {
+        require DOCUMENT_PATH . '/src/Lib/Websocket/sockets.php';
+
+        $names = SocketRegistry::names();
+
+        self::assertContains('echo', $names);
+        self::assertContains('chat', $names);
+    }
+}

package/dist/tests/Support/FakeConnection.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Support;
+
+use Ratchet\ConnectionInterface;
+use GuzzleHttp\Psr7\Request as Psr7Request;
+
+/**
+ * A Ratchet connection stand-in that records what the server sends.
+ *
+ * The named-socket wire is frames and closes, so a test only needs to see
+ * both: `$sentFrames` collects every `send(...)` payload (decoded from JSON
+ * when possible) and `$closeCodes` collects every `close(...)` code. The
+ * `httpRequest` property mirrors how Ratchet exposes the handshake request.
+ */
+final class FakeConnection implements ConnectionInterface
+{
+    /** @var list<mixed> Decoded JSON frames (raw string when not JSON). */
+    public array $sentFrames = [];
+
+    /** @var list<string> Raw frames exactly as sent. */
+    public array $rawFrames = [];
+
+    /** @var list<int> */
+    public array $closeCodes = [];
+
+    public bool $isClosed = false;
+
+    public ?Psr7Request $httpRequest = null;
+
+    /**
+     * @param array<string, string> $headers Handshake headers (e.g. Origin, Cookie).
+     */
+    public function __construct(string $uri = '/__pulsepoint/ws', array $headers = [])
+    {
+        $this->httpRequest = new Psr7Request('GET', $uri, $headers);
+    }
+
+    public function send($data): ConnectionInterface
+    {
+        $this->rawFrames[] = (string) $data;
+
+        $decoded = json_decode((string) $data, true);
+        $this->sentFrames[] = json_last_error() === JSON_ERROR_NONE ? $decoded : (string) $data;
+
+        return $this;
+    }
+
+    public function close($code = 1000): void
+    {
+        $this->closeCodes[] = (int) $code;
+        $this->isClosed = true;
+    }
+
+    /** The last frame the server sent, decoded. */
+    public function lastFrame(): mixed
+    {
+        return $this->sentFrames === [] ? null : end($this->sentFrames);
+    }
+}

package/dist/tests/Support/Features.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Support;
+
+/**
+ * Feature flags for the test suite, read from `prisma-php.json`.
+ *
+ * `prisma-php.json` is the single source of truth for which optional Prisma
+ * PHP features are enabled in the current app (`websocket`, `mcp`,
+ * `swaggerDocs`, `prisma`, `tailwindcss`, `typescript`, `backendOnly`).
+ * Tests that exercise an optional feature's scaffold must guard on the flag —
+ * when the feature is off, its files do not exist and the test must skip,
+ * not fatal.
+ */
+final class Features
+{
+    /** @var array<string, mixed>|null */
+    private static ?array $config = null;
+
+    /** @return array<string, mixed> The parsed prisma-php.json. */
+    public static function config(): array
+    {
+        if (self::$config === null) {
+            $raw = @file_get_contents(DOCUMENT_PATH . '/prisma-php.json');
+            $decoded = is_string($raw) ? json_decode($raw, true) : null;
+            self::$config = is_array($decoded) ? $decoded : [];
+        }
+
+        return self::$config;
+    }
+
+    public static function enabled(string $feature): bool
+    {
+        return (self::config()[$feature] ?? false) === true;
+    }
+}

package/dist/tests/Support/RequiresFeature.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Support;
+
+/**
+ * Skip guard for tests of optional Prisma PHP features.
+ *
+ * Call `$this->requireFeature('websocket')` as the FIRST line of `setUp()`,
+ * before touching any class from the feature's scaffold — a disabled
+ * feature's files are not generated, so reaching them would fatal instead
+ * of failing cleanly. A skipped test reports why and how to enable it.
+ */
+trait RequiresFeature
+{
+    protected function requireFeature(string $feature): void
+    {
+        if (!Features::enabled($feature)) {
+            self::markTestSkipped(
+                "The `$feature` feature is disabled in prisma-php.json; "
+                    . "enable it and run `npx pp update project -y` to use this suite."
+            );
+        }
+    }
+}