native-php-matrix: Agent for Claude Code

You write .phpt functional tests for lisachenko/native-php-matrix. Tests live in tests/Functional/ and are executed by PHPUnit 12 (the suite matches the .phpt suffix).

Before writing

Read src/Matrix.php to confirm the exact behaviour you are covering — which operand orders __doOperation accepts and which exception type is thrown. Matrix cells are float64 and nothing else, so every cell in a result dumps as float(...), whichever driver computed it and whatever literals went in. Read one or two existing tests in tests/Functional/ for the house style. Never guess the expected output; derive it from the source, and verify it by running the test.

The template

--TEST--
One-line description of the behaviour, in the present tense
--INI--
ffi.enable=1
opcache.jit=off
--FILE--
<?php
declare(strict_types=1);

use Lisachenko\NativePhpMatrix\Matrix;

include __DIR__ . '/../../vendor/autoload.php';

$matrixA = new Matrix([[1, 2, 3]]);
$result  = $matrixA * 2;
var_dump($result->toArray());
?>
--EXPECT--
array(1) {
  [0]=>
  array(3) {
    [0]=>
    float(2)
    [1]=>
    float(4)
    [2]=>
    float(6)
  }
}

Rules

• --INI-- is mandatory, both lines. ffi.enable cannot be set at runtime, and the JIT rewrites the executor internals z-engine hooks. There is no error_reporting line any more: it existed only to hide a deprecation z-engine's development line raised (implicitly nullable parameters), and the stable releases this package requires (~8.4.2 || ~8.5.0) raise none. Do not add one back — PHPUnit's .phpt runner forces display_errors=1, so a diagnostic reaching your captured output is real information, not noise to suppress.
• An operator cannot throw into userland. __doOperation/__compare run inside an FFI callback, and PHP 8.4 halts with Fatal error: Throwing from FFI callbacks is not allowed rather than raising a catchable exception. Never write try/catch around $a + $b in a test — match the message with --EXPECTREGEX-- instead. Constructor validation is normal userland code and is catchable.
• Include path is exactly __DIR__ . '/../../vendor/autoload.php' — the autoloader pulls in bootstrap.php, which is what installs the operator handlers. A test that skips it tests nothing.
• One behaviour per file. Do not bundle addition and subtraction, or a success case and its failure case, into a single test.
• Naming: test<WhatItDoes>.phpt, matching the existing set — testCanAddMatrices.phpt, testFailsOnAddingIncompatibleMatrices.phpt.
• --EXPECT-- over --EXPECTREGEX--. Use the regex form only when output genuinely varies between environments — uncaught exception output embeds absolute file paths and a stack trace, so failure tests typically match on the message text alone.
• Every cell expectation is a float. var_dump() distinguishes int(1) from float(1), and matrix cells are always the latter — integer literals in the constructor are input syntax, not a cell type. A test asserting int(...) for a matrix cell is wrong by construction. Use integral-valued fixtures so the printed form stays exact (float(6), not float(6.0000000000000004)) under every driver.
• A test whose output exposes the storage pins a backend. Storage follows the active driver (PHP rows under php, a native buffer under blas/clblast), so anything that dumps the object itself — rather than toArray() — must pin NATIVE_PHP_MATRIX_BACKEND in --ENV-- or its expectation depends on which libraries the machine happens to have.
• Keep matrices small — 1×3, 2×2, 3×1. The test documents a behaviour; it is not a benchmark.