Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 44 additions & 3 deletions docs/testing/packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,12 +59,12 @@ The following methods can be overridden:

- `getFixtures()` returns a list of directories that are mirrored onto the root of the skeleton, in order, after the framework files. A later directory overwrites an earlier one. Use them to add controllers, routes, configuration or a `Registrar`, for example **Fixtures/app/Config/Routes.php**. A fixture **app/Config/Paths.php** must keep the default `$systemDirectory`, which `build()` then points at the framework.
- `getEnv()` returns settings for the skeleton's **.env** file. Values are quoted, so they may contain spaces, `#` and quotes, but a value with a line break is refused. Names may only contain letters, digits, `.`, `_`, `-` and `\`, which covers forms such as `app.baseURL` and `Config\App.baseURL`. `CI_ENVIRONMENT` defaults to `development`, because `spark` does not run in the `testing` environment.
- `getFrameworkPath()` returns the framework that the skeleton is copied from, which is the one that provides the orchestrator. Expose it from your subclass if your tests need the framework's location.
- `getFrameworkPath()` returns the framework that the skeleton is copied from, which is the one that provides the orchestrator.
- `afterBuild()` runs when the skeleton is complete, for example to create a database.
- `getPath()` returns the skeleton's location, **build/orchestrator** in the package root by default. A token is appended to it so that parallel processes do not share a skeleton. The token is read from `ORCHESTRATOR_TEST_TOKEN`, or else from `TEST_TOKEN`, which parallel runners such as ParaTest set for each process. It may only contain letters, digits, hyphens and underscores: an invalid `ORCHESTRATOR_TEST_TOKEN` throws an exception, and an invalid `TEST_TOKEN` is ignored. Set `ORCHESTRATOR_TEST_TOKEN` to an empty string to opt out of `TEST_TOKEN`.
- `getSkeletonPath()` returns the skeleton's location, **build/orchestrator** in the package root by default. `getPath()` appends `-console` to it after `bootConsole()`, and then a token so that parallel processes do not share a skeleton. The token is read from `ORCHESTRATOR_TEST_TOKEN`, or else from `TEST_TOKEN`, which parallel runners such as ParaTest set for each process. It may only contain letters, digits, hyphens and underscores: an invalid `ORCHESTRATOR_TEST_TOKEN` throws an exception, and an invalid `TEST_TOKEN` is ignored. Set `ORCHESTRATOR_TEST_TOKEN` to an empty string to opt out of `TEST_TOKEN`.

!!! note "Note"
The skeleton is generated, so add its location to your **.gitignore**, which is **build/** unless `getPath()` is overridden.
The skeleton is generated, so add its location to your **.gitignore**, which is **build/** unless `getSkeletonPath()` is overridden.

!!! note "Note"
The skeleton is copied from the framework installed with your package, so only that version is tested. To build it from another version, keep a copy of that framework in a separate directory and return its path from `getFrameworkPath()`.
Expand All @@ -90,6 +90,47 @@ Point `bootstrap` at this file in your **phpunit.dist.xml**. Since it replaces C
!!! important "Important"
The path constants and the framework's static state last for the whole process, so one process hosts one skeleton.

`getPathConstants()` returns the constants that `boot()` defines, keyed by name: `HOMEPATH`, `CONFIGPATH` and `PUBLICPATH` for the skeleton, and `TESTPATH` and, when **tests/_support** exists, `SUPPORTPATH` for the package. Call it after `build()`. Use it with `getFrameworkPath()` to load another bootstrap file against the skeleton:

```php
$orchestrator->build();

foreach ($orchestrator->getPathConstants() as $name => $value) {
defined($name) || define($name, $value);
}

require $orchestrator->getFrameworkPath() . '/system/Test/bootstrap.php';
```

## Booting Outside PHPUnit

Code that runs outside PHPUnit, such as a package script or a static analysis bootstrap file, can call `bootConsole()` to use the framework's functions and services, like `env()`, `helper()` and `service()`. It loads the framework's **system/util_bootstrap.php** against a skeleton of its own, in **build/orchestrator-console** by default, so that it does not share a skeleton with a running test suite:

```php
<?php

// bin/blog

use Acme\Blog\Tests\BlogOrchestrator;

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

(new BlogOrchestrator())->bootConsole();
```

Unlike `boot()`, it builds the skeleton only when it is missing or a previous build did not finish. A reused skeleton skips `getEnv()` and `afterBuild()`, so work in those hooks must tolerate being skipped. Pass `rebuild: true` to rebuild it after changing your fixtures or updating the framework, since `build()` called before `bootConsole()` rebuilds the PHPUnit skeleton instead, and called after it, changes files that are already loaded:

```php
(new BlogOrchestrator())->bootConsole(rebuild: true);
```

The environment is read from `CI_ENVIRONMENT`, `development` by default, a `CLIRequest` is created, and the routes are loaded, as with **spark**. Routes are loaded last, so an error in a route file is thrown from `bootConsole()`. The test helpers of **system/Test/bootstrap.php**, like the mocked `is_cli()`, are not loaded.

!!! note "Note"
Processes that boot at the same time share **build/orchestrator-console**, so a build in one removes the skeleton in use by the other. Give each tool its own `ORCHESTRATOR_TEST_TOKEN`, as described under `getSkeletonPath()`.

After `bootConsole()`, the instance keeps addressing the console skeleton, and `boot()` on it throws an exception.

## Testing Through spark

`spark()` runs the skeleton's **spark** in a separate process and returns a `SparkResult` with the `exitCode`, `stdout`, `stderr` and `timedOut` properties:
Expand Down
129 changes: 110 additions & 19 deletions system/Test/Orchestrator/AbstractOrchestrator.php
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,17 @@ abstract class AbstractOrchestrator
*/
private const KILL_GRACE_PERIOD = 2.0;

private const BUILT_MARKER = '.orchestrator-built';

private bool $console = false;

/**
* Absolute path of the skeleton, suffixed with `ORCHESTRATOR_TEST_TOKEN`, or else a valid `TEST_TOKEN`, so parallel runs do not collide.
* Absolute path of the skeleton, which is `getSkeletonPath()` followed by:
*
* - `-console` after `bootConsole()`
* - `-` and `ORCHESTRATOR_TEST_TOKEN`, or else a valid `TEST_TOKEN`, so parallel runs do not collide
*/
public function getPath(): string
final public function getPath(): string
{
$token = getenv('ORCHESTRATOR_TEST_TOKEN');

Expand All @@ -47,8 +54,9 @@ public function getPath(): string
}

return sprintf(
'%s/build/orchestrator%s',
rtrim($this->getPackageRoot(), '\\/'),
'%s%s%s',
rtrim($this->getSkeletonPath(), '\\/'),
$this->console ? '-console' : '',
is_string($token) && $token !== '' ? '-' . $token : '',
);
}
Expand All @@ -66,10 +74,11 @@ final public function build(): void
$this->ensureUnlinkedAncestors();
$this->removePath($path);

foreach (['app', 'public', 'writable'] as $directory) {
foreach (['app', 'public'] as $directory) {
directory_mirror($framework . '/' . $directory, $path . '/' . $directory);
}

$this->mirrorWritable($framework . '/writable', $path . '/writable');
$this->failUnless(copy($framework . '/spark', $path . '/spark'), 'copy spark');
$this->writeAutoloader();
$this->writeEnv();
Expand All @@ -80,6 +89,8 @@ final public function build(): void

$this->pointPathsAtTheFramework();
$this->afterBuild();

$this->failUnless(touch($path . '/' . self::BUILT_MARKER), 'mark the build complete');
}

/**
Expand All @@ -89,9 +100,48 @@ final public function build(): void
*/
final public function boot(): void
{
if ($this->console) {
throw new RuntimeException('Cannot call boot() after bootConsole().');
}

$this->build();
$this->defineConstants();

require $this->getFrameworkPath() . '/system/Test/bootstrap.php';
}

/**
* Boots the framework in this process through **system/util_bootstrap.php** against its own skeleton.
*
* `getEnv()` and `afterBuild()` run only when the skeleton is incomplete or `$rebuild` is true.
*/
final public function bootConsole(bool $rebuild = false): void
{
$this->console = true;

if ($rebuild || ! is_file($this->getPath() . '/' . self::BUILT_MARKER)) {
$this->build();
}

$this->defineConstants();

$path = realpath($this->getPath()) . DIRECTORY_SEPARATOR;
require $this->getFrameworkPath() . '/system/util_bootstrap.php';
}

/**
* Path constants of the built skeleton and the package, keyed by name.
*
* @return array<string, string>
*/
public function getPathConstants(): array
{
$path = $this->getRealRoot();

if ($path === '') {
throw new RuntimeException('Cannot read the path constants before the orchestrated application is built.');
}

$path .= DIRECTORY_SEPARATOR;
$testPath = rtrim($this->getPackageRoot(), '\\/') . '/tests' . DIRECTORY_SEPARATOR;
$constants = [
'HOMEPATH' => $path,
Expand All @@ -104,13 +154,7 @@ final public function boot(): void
$constants['SUPPORTPATH'] = $testPath . '_support' . DIRECTORY_SEPARATOR;
}

foreach ($constants as $name => $value) {
if (! defined($name)) {
define($name, $value);
}
}

require $this->getFrameworkPath() . '/system/Test/bootstrap.php';
return $constants;
}

/**
Expand Down Expand Up @@ -206,11 +250,27 @@ final public function clean(): void
$this->removePath($this->getPath());
}

/**
* Absolute path of the framework that the skeleton is copied from.
*/
public function getFrameworkPath(): string
{
return dirname(__DIR__, 3);
}

/**
* Absolute path of the package under test, the directory holding its `vendor/autoload.php`.
*/
abstract protected function getPackageRoot(): string;

/**
* Absolute path of the skeleton before the suffixes added by `getPath()`.
*/
protected function getSkeletonPath(): string
{
return rtrim($this->getPackageRoot(), '\\/') . '/build/orchestrator';
}

/**
* Absolute paths of directories mirrored onto the skeleton, in order, after the framework files.
*
Expand Down Expand Up @@ -238,12 +298,13 @@ protected function afterBuild(): void
{
}

/**
* Absolute path of the framework that the skeleton is copied from.
*/
protected function getFrameworkPath(): string
private function defineConstants(): void
{
return dirname(__DIR__, 3);
foreach ($this->getPathConstants() as $name => $value) {
if (! defined($name)) {
define($name, $value);
}
}
}

private function isValidToken(string $token): bool
Expand Down Expand Up @@ -395,6 +456,33 @@ private function wait(mixed $process, ?float $timeout): array
return [$exitCode, $timedOut];
}

private function mirrorWritable(string $origin, string $target): void
{
$this->failUnless(is_dir($target) || mkdir($target, 0755, true), 'create writable');

foreach (['index.html', '.htaccess'] as $file) {
if (is_file($origin . '/' . $file)) {
$this->failUnless(copy($origin . '/' . $file, $target . '/' . $file), sprintf('copy writable/%s', $file));
}
}

$entries = scandir($origin);

$this->failUnless($entries !== false, 'read writable');

foreach (array_diff($entries, ['.', '..']) as $directory) {
if (! is_file($origin . '/' . $directory . '/index.html')) {
continue;
}

$this->failUnless(mkdir($target . '/' . $directory, 0755), sprintf('create writable/%s', $directory));
$this->failUnless(
copy($origin . '/' . $directory . '/index.html', $target . '/' . $directory . '/index.html'),
sprintf('copy writable/%s/index.html', $directory),
);
}
}

private function pointPathsAtTheFramework(): void
{
$paths = $this->getPath() . '/app/Config/Paths.php';
Expand All @@ -405,7 +493,7 @@ private function pointPathsAtTheFramework(): void
$rewritten = str_replace(
"__DIR__ . '/../../system'",
var_export($this->getFrameworkPath() . '/system', true),
(string) $contents,
$contents,
$count,
);

Expand Down Expand Up @@ -446,6 +534,9 @@ private function writeEnv(): void
$this->failUnless(write_file($this->getPath() . '/.env', $contents), 'write .env');
}

/**
* @phpstan-assert true $succeeded
*/
private function failUnless(bool $succeeded, string $step): void
{
if (! $succeeded) {
Expand Down
4 changes: 2 additions & 2 deletions system/util_bootstrap.php
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@
}

if (is_dir(HOMEPATH . 'vendor/')) {
define('VENDORPATH', realpath(HOMEPATH . 'vendor/') . DIRECTORY_SEPARATOR);
define('COMPOSER_PATH', (string) realpath(HOMEPATH . 'vendor/autoload.php'));
defined('VENDORPATH') || define('VENDORPATH', realpath(HOMEPATH . 'vendor/') . DIRECTORY_SEPARATOR);
defined('COMPOSER_PATH') || define('COMPOSER_PATH', (string) realpath(HOMEPATH . 'vendor/autoload.php'));
}

/*
Expand Down
4 changes: 2 additions & 2 deletions tests/_support/Orchestrator/OrchestratorStub.php
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ public function __construct(
) {
}

public function getPath(): string
protected function getSkeletonPath(): string
{
return $this->skeleton !== '' ? $this->skeleton : parent::getPath();
return $this->skeleton !== '' ? $this->skeleton : parent::getSkeletonPath();
}

protected function getPackageRoot(): string
Expand Down
Loading
Loading