feat(core): improve base testing class (#1509)

brendt · web-flow · commit 830e27bb28a5 · 2025-08-14T14:30:04.000+02:00
diff --git a/docs/1-essentials/07-testing.md b/docs/1-essentials/07-testing.md
@@ -12,56 +12,121 @@ Testing utilities specific to components are documented in their respective chap
 
 ## Running tests
 
-If you created a Tempest application through the [recommended installation process](../0-getting-started/02-installation.md), you already have access to `tests/IntegrationTestCase`, which your application tests can inherit from.
+Any test class that wants to interact with Tempest should extend from [`IntegrationTest`](https://github.com/tempestphp/tempest-framework/blob/main/src/Tempest/Framework/Testing/IntegrationTest.php). Next, any test class should end with the suffix `Test`.
 
-In this case, you may use the `composer phpunit` command to run your test suite.
+Running the test suite is done by running `composer phpunit`.
 
 ```sh
 composer phpunit
 ```
 
-## Creating new test files
+## Test-specific discovery locations
+
+Tempest will only discover non-dev namespaces defined in composer.json automatically. That means that `{:hl-keyword:require-dev:}` namespaces aren't discovered automatically. Whenever you need Tempest to discover test-specific locations, you may specify them within the `discoverTestLocations()` method of the provided `IntegrationTest` class. 
 
-By default, PHPUnit is configured to look for test files that end in `*Test.php` in the root `tests` directory. You may create a such a file and make it extend `IntegrationTestCase`.
+On top of that, Tempest _will_ look for files in the `tests/Fixtures` directory and discover them by default. You can override this behavior by providing your own implementation of `discoverTestLocations()`, where you can return an array of `DiscoveryLocation` objects (or nothing).
 
 ```php tests/HomeControllerTest.php
-use Tests\IntegrationTestCase;
+use Tempest\Core\DiscoveryLocation;
+use Tempest\Framework\Testing\IntegrationTest;
 
-final class HomeControllerTest extends IntegrationTestCase
+final class HomeControllerTest extends IntegrationTest
 {
-    public function test_index(): void
+    protected function discoverTestLocations(): array
     {
-        $this->http
-            ->get('/')
-            ->assertOk();
+        return [
+            new DiscoveryLocation('Tests\\OtherFixtures', __DIR__ . '/OtherFixtures'),
+        ];
     }
 }
 ```
 
-## Test-specific discovery locations
+## Using the database
 
-Tempest does not discover files outside of the namespaces defined in the `require` object of `composer.json`. If you need Tempest to discover test-specific fixture files, you may specify paths using the `discoveryLocations` property of the provided `IntegrationTestCase` class.
+If you want to test code that interacts with the database, your test class can call the `setupDatabase()` method. This method will create and migrate a clean database for you on the fly.
 
-For instance, you may create a `tests/config` directory that contains test-specific configuration files, and instruct Tempest to discover them:
+```php
+class TodoControllerTest extends IntegrationTest
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
 
-```php tests/IntegrationTestCase.php
-use Tempest\Core\DiscoveryLocation;
+        $this->setupDatabase();
+    }
+}
+```
 
-final class IntegrationTestCase extends TestCase
-{
-    protected string $root = __DIR__ . '/../';
+Most likely, you'll want to use a test-specific database connection. You can create a `database.config.php` file anywhere within test-specific discovery locations, and Tempest will use that connection instead of the project's default. For example, you can create a file `tests/Fixtures/database.config.php` like so:
 
-    protected function setUp(): void
+```php tests/Fixtures/database.config.php
+<?php
+
+use Tempest\Database\Config\SQLiteConfig;
+
+return new SQLiteConfig(
+    path: __DIR__ . '/database-testing.sqlite'
+);
+```
+
+By default, no tables will be migrated. You can choose to provide a list of migrations that will be run for every test that calls `setupDatabase()`, or you can run specific migrations on a per-test basis.
+
+```php
+class TodoControllerTest extends IntegrationTest
+{
+    protected function migrateDatabase(): void
     {
-        $this->discoveryLocations = [
-            new DiscoveryLocation(namespace: 'Tests\\Config', path: __DIR__ . '/config'),
-        ];
+        $this->migrate(
+            CreateMigrationsTable::class,
+            CreateTodosTable::class,
+        );
+    }
+}
+```
 
-        parent::setUp();
+```php
+class TodoControllerTest extends IntegrationTest
+{
+    public function test_create_todo(): void
+    {
+        $this->migrate(
+            CreateMigrationsTable::class,
+            CreateTodosTable::class,
+        );
+        
+        // …
     }
 }
 ```
 
+## Tester utilities
+
+The `IntegrationTest` provides several utilities to make testing easier. You can read the details about each tester utility on the documentation page of its respective component. For example, there's the [http tester](../1-essentials/01-routing.md#testing) that helps you test HTTP requests:
+
+```php
+$this->http
+    ->get('/account/profile')
+    ->assertOk()
+    ->assertSee('My Profile');
+```
+
+There's the [console tester](../1-essentials/04-console-commands.md#testing):
+
+```php tests/ExportUsersCommandTest.php
+$this->console
+    ->call(ExportUsersCommand::class)
+    ->assertSuccess()
+    ->assertSee('12 users exported');
+
+$this->console
+    ->call(WipeDatabaseCommand::class)
+    ->assertSee('caution')
+    ->submit()
+    ->assertSuccess();
+```
+
+And many, many more.
+
 ## Changing the location of tests
 
 The `phpunit.xml` file contains a `{html}<testsuite>` element that configures the directory in which PHPUnit looks for test files. This may be changed to follow any rule of your convenience.
@@ -92,7 +157,7 @@ The next step is to create a `tests/Pest.php` file, which will instruct Pest how
 
 ```php tests/Pest.php
 pest()
-    ->extend(Tests\IntegrationTestCase::class)
+    ->extend(Tests\IntegrationTest::class)
     ->in(__DIR__);
 ```
 
diff --git a/src/Tempest/Framework/Testing/IntegrationTest.php b/src/Tempest/Framework/Testing/IntegrationTest.php
@@ -4,31 +4,39 @@
 
 namespace Tempest\Framework\Testing;
 
+use Closure;
 use PHPUnit\Framework\TestCase;
 use Tempest\Cache\Testing\CacheTester;
 use Tempest\Clock\Clock;
 use Tempest\Clock\MockClock;
+use Tempest\Console\Output\MemoryOutputBuffer;
+use Tempest\Console\Output\StdoutOutputBuffer;
+use Tempest\Console\OutputBuffer;
 use Tempest\Console\Testing\ConsoleTester;
 use Tempest\Container\GenericContainer;
 use Tempest\Core\AppConfig;
 use Tempest\Core\ExceptionTester;
 use Tempest\Core\FrameworkKernel;
 use Tempest\Core\Kernel;
+use Tempest\Core\ShellExecutor;
+use Tempest\Core\ShellExecutors\NullShellExecutor;
+use Tempest\Database\Migrations\CreateMigrationsTable;
 use Tempest\Database\Migrations\MigrationManager;
 use Tempest\DateTime\DateTimeInterface;
+use Tempest\Discovery\DiscoveryLocation;
 use Tempest\EventBus\EventBus;
 use Tempest\EventBus\Testing\EventBusTester;
 use Tempest\Framework\Testing\Http\HttpRouterTester;
 use Tempest\Http\GenericRequest;
 use Tempest\Http\Method;
 use Tempest\Http\Request;
-use Tempest\Mail\MailerConfig;
 use Tempest\Mail\Testing\MailTester;
 use Tempest\Mail\Testing\TestingMailer;
 use Tempest\Storage\Testing\StorageTester;
-use Tempest\View\ViewRenderer;
+use Throwable;
 
 use function Tempest\Support\Path\normalize;
+use function Tempest\Support\Path\to_absolute_path;
 
 /** @mago-expect maintainability/too-many-properties */
 abstract class IntegrationTest extends TestCase
@@ -66,19 +74,63 @@ protected function setUp(): void
     {
         parent::setUp();
 
+        $this->setupKernel()
+            ->setupConsole()
+            ->setupTesters()
+            ->setupBaseRequest();
+    }
+
+    /**
+     * Returns an array of DiscoveryLocations that should be discovered only during testing
+     * @return \Tempest\Discovery\DiscoveryLocation[]
+     */
+    protected function discoverTestLocations(): array
+    {
+        $discoveryLocations = [];
+
+        $fixturesPath = to_absolute_path($this->root, 'tests/Fixtures');
+
+        if (is_dir($fixturesPath)) {
+            $discoveryLocations[] = new DiscoveryLocation(
+                'Tests\\Fixtures',
+                $fixturesPath,
+            );
+        }
+
+        return $discoveryLocations;
+    }
+
+    protected function setupKernel(): self
+    {
         // We force forward slashes for consistency even on Windows.
-        $this->root ??= normalize(realpath(__DIR__ . '/../../'));
+        $this->root ??= normalize(realpath(getcwd()));
+
+        $discoveryLocations = [...$this->discoveryLocations, ...$this->discoverTestLocations()];
 
         $this->kernel ??= FrameworkKernel::boot(
             root: $this->root,
-            discoveryLocations: $this->discoveryLocations,
+            discoveryLocations: $discoveryLocations,
         );
 
         /** @var GenericContainer $container */
         $container = $this->kernel->container;
         $this->container = $container;
 
+        return $this;
+    }
+
+    protected function setupConsole(): self
+    {
         $this->console = new ConsoleTester($this->container);
+        $this->container->singleton(OutputBuffer::class, fn () => new MemoryOutputBuffer());
+        $this->container->singleton(StdoutOutputBuffer::class, fn () => new MemoryOutputBuffer());
+        $this->container->singleton(ShellExecutor::class, fn () => new NullShellExecutor());
+
+        return $this;
+    }
+
+    protected function setupTesters(): self
+    {
         $this->http = new HttpRouterTester($this->container);
         $this->installer = new InstallerTester($this->container);
         $this->eventBus = new EventBusTester($this->container);
@@ -95,9 +147,34 @@ protected function setUp(): void
         $this->vite->preventTagResolution();
         $this->vite->clearCaches();
 
+        return $this;
+    }
+
+    protected function setupBaseRequest(): self
+    {
         $request = new GenericRequest(Method::GET, '/', []);
         $this->container->singleton(Request::class, fn () => $request);
         $this->container->singleton(GenericRequest::class, fn () => $request);
+
+        return $this;
+    }
+
+    protected function setupDatabase(): self
+    {
+        $migrationManager = $this->container->get(MigrationManager::class);
+
+        $migrationManager->dropAll();
+
+        $this->migrateDatabase();
+
+        return $this;
+    }
+
+    protected function migrateDatabase(): void
+    {
+        $this->migrate(
+            CreateMigrationsTable::class,
+        );
     }
 
     protected function migrate(string|object ...$migrationClasses): void
@@ -139,4 +216,24 @@ protected function tearDown(): void
         /** @phpstan-ignore-next-line */
         unset($this->http);
     }
+
+    protected function assertException(
+        string $expectedExceptionClass,
+        Closure $handler,
+        ?Closure $assertException = null,
+    ): void {
+        try {
+            $handler();
+        } catch (Throwable $throwable) {
+            $this->assertInstanceOf($expectedExceptionClass, $throwable);
+
+            if ($assertException !== null) {
+                $assertException($throwable);
+            }
+
+            return;
+        }
+
+        $this->fail("Expected exception {$expectedExceptionClass} was not thrown");
+    }
 }
diff --git a/tests/Integration/FrameworkIntegrationTestCase.php b/tests/Integration/FrameworkIntegrationTestCase.php
