CluPilotCloud/tests/Pest.php

<?php

use App\Models\Mailbox;
use App\Models\User;
use App\Services\Dns\FakeHetznerDnsClient;
use App\Services\Dns\HetznerDnsClient;
use App\Services\Mail\MailPurpose;
use App\Services\Monitoring\FakeMonitoringClient;
use App\Services\Monitoring\MonitoringClient;
use App\Services\Proxmox\FakeProxmoxClient;
use App\Services\Proxmox\ProxmoxClient;
use App\Services\Ssh\FakeRemoteShell;
use App\Services\Ssh\RemoteShell;
use App\Services\Traefik\FakeTraefikWriter;
use App\Services\Traefik\TraefikWriter;
use App\Services\Wireguard\FakeWireguardHub;
use App\Services\Wireguard\WireguardHub;
use App\Support\Settings;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

/*
|--------------------------------------------------------------------------
| Test Case
|--------------------------------------------------------------------------
|
| The closure you provide to your test functions is always bound to a specific PHPUnit test
| case class. By default, that class is "PHPUnit\Framework\TestCase". Of course, you may
| need to change it using the "pest()" function to bind different classes or traits.
|
*/

pest()->extend(TestCase::class)
    ->use(RefreshDatabase::class)
    ->in('Feature');

/*
|--------------------------------------------------------------------------
| Expectations
|--------------------------------------------------------------------------
|
| When you're writing tests, you often need to check that values meet certain conditions. The
| "expect()" function gives you access to a set of "expectations" methods that you can use
| to assert different things. Of course, you may extend the Expectation API at any time.
|
*/

expect()->extend('toBeOne', function () {
    return $this->toBe(1);
});

/*
|--------------------------------------------------------------------------
| Functions
|--------------------------------------------------------------------------
|
| While Pest is very powerful out-of-the-box, you may have some testing code specific to your
| project that you don't want to repeat in every file. Here you can also expose helpers as
| global functions to help you to reduce the number of lines of code in your test files.
|
*/

function something()
{
    // ..
}

/**
 * Bind fake provisioning services into the container and return them so a test
 * can script/inspect SSH, WireGuard, Proxmox, DNS and Traefik interactions.
 *
 * @return array{shell: FakeRemoteShell, hub: FakeWireguardHub, pve: FakeProxmoxClient, dns: FakeHetznerDnsClient, traefik: FakeTraefikWriter}
 */
function fakeServices(): array
{
    $shell = new FakeRemoteShell;
    $hub = new FakeWireguardHub;
    $pve = new FakeProxmoxClient;
    $dns = new FakeHetznerDnsClient;
    $traefik = new FakeTraefikWriter;
    $monitoring = new FakeMonitoringClient;

    app()->instance(RemoteShell::class, $shell);
    app()->instance(WireguardHub::class, $hub);
    app()->instance(ProxmoxClient::class, $pve);
    app()->instance(HetznerDnsClient::class, $dns);
    app()->instance(TraefikWriter::class, $traefik);
    app()->instance(MonitoringClient::class, $monitoring);

    return ['shell' => $shell, 'hub' => $hub, 'pve' => $pve, 'dns' => $dns, 'traefik' => $traefik, 'monitoring' => $monitoring];
}

/*
| Shared account helpers. Defined here — NOT in an individual test file — so a
| targeted run (pest tests/Feature/Admin/OneFile.php) still resolves them.
*/
function operator(string $role): User
{
    return User::factory()->operator($role)->create();
}

function admin(): User
{
    return User::factory()->create(['is_admin' => true]);
}

/**
 * Undo the mailbox-seeding migration's baseline, for tests written before it.
 *
 * RefreshDatabase migrates once per run, not once per test, so every test
 * starts from a transaction rolled back to that migrated state — including the
 * five mailboxes (no-reply, support, billing, office, info) and all five
 * mail.purpose.* settings the mailbox-seeding migration writes. The tests in
 * tests/Feature/Mail predate that migration: several create their own mailbox
 * under one of those same five keys, which now collides with mailboxes.key's
 * unique constraint; a couple rely on a purpose being genuinely unset to prove
 * MailboxResolver's system fallback, which the seeded mapping would otherwise
 * pre-empt. Call this from such a file's beforeEach() to restore the blank
 * slate it was written against.
 */
function clearMailboxSeed(): void
{
    Mailbox::query()->delete();

    foreach (MailPurpose::ALL as $purpose) {
        Settings::set(MailPurpose::settingKey($purpose), null);
    }
}

/**
 * env()'s own seam. Illuminate\Support\Env reads real process environment
 * variables (putenv()/getenv(), $_ENV, $_SERVER — Env::getRepository() chains
 * readers over all three), not config(), so config()->set() — the way every
 * other test in this suite drives behaviour — cannot touch it. This captures
 * the CURRENT value of each key exactly as env() would see it, distinguishing
 * "not set at all" (null) from "set to an empty string", so a caller can put
 * it back afterward without leaving a variable behind — or removing one — that
 * was never this test's to touch.
 *
 * @param  array<int, string>  $keys
 * @return array<string, string|null>
 */
function captureRealEnv(array $keys): array
{
    $captured = [];

    foreach ($keys as $key) {
        $value = getenv($key);
        $captured[$key] = $value === false ? null : $value;
    }

    return $captured;
}

/**
 * Writes real process environment variables through every adapter
 * Env::getRepository() might be reading from, so it does not matter which one
 * answers first. null unsets the variable entirely — distinct from '', which
 * env() would return as a real, present, empty value.
 *
 * @param  array<string, string|null>  $vars
 */
function setRealEnv(array $vars): void
{
    foreach ($vars as $key => $value) {
        if ($value === null) {
            putenv($key);
            unset($_ENV[$key], $_SERVER[$key]);
        } else {
            putenv("{$key}={$value}");
            $_ENV[$key] = $value;
            $_SERVER[$key] = $value;
        }
    }
}

/**
 * Runs $callback with the given real environment variables set, then restores
 * exactly what was there before — including "was not set at all". Use this to
 * prove behaviour that reads raw env() rather than config(); see
 * captureRealEnv()'s own docblock for why config()->set() cannot do this.
 */
function withRealEnv(array $vars, Closure $callback): mixed
{
    $previous = captureRealEnv(array_keys($vars));

    setRealEnv($vars);

    try {
        return $callback();
    } finally {
        setRealEnv($previous);
    }
}