Testing the platform#

The platform ships with a large PHPUnit suite — ~700 test methods across ~90 files, all green — organized into tests/Unit and tests/Feature. This page covers how to run it and how to add to it correctly.

Who this is for#

Developers changing platform code, and anyone verifying an install before go-live.

Difficulty: Medium · Time: about 10 minutes.

Running the suite#

On Windows/XAMPP (PHP may not be on PATH — call it explicitly):

D:/Xampp/php/php.exe vendor/bin/phpunit

Anywhere else:

php vendor/bin/phpunit

Useful variations:

php vendor/bin/phpunit --filter=MobileApiTest   # one test class
php vendor/bin/phpunit --testsuite=Feature      # one suite
php vendor/bin/phpunit --filter=test_lead_index # one method

How tests are organised#

The house convention is Illuminate\Foundation\Testing\DatabaseTransactions rather than database refreshes: each test runs inside a transaction that is rolled back afterwards. The schema stays intact and tests stay fast — but it means the testing database must already be migrated, and anything you create in a test is invisible to parallel processes.

Because every tenant-owned model is behind the fail-closed BelongsToTenant scope, tests must establish tenant context the same way real requests do — bind app('current_tenant'), sign in a user whose tenant_id is set, or assert the empty-result behavior deliberately. This is the most common gotcha when a new feature test "sees nothing". See Multi-tenancy & isolation.

Factories#

Model factories live in database/factories/:

UserFactory, TenantFactory, LeadFactory, LeadSourceConnectionFactory, WebhookLogFactory, AiSdrAgentFactory, ChatbotConfigFactory.

Writing a feature test (the house way)#

A typical feature test — factory setup, tenant context, HTTP assertion, transaction rollback:

<?php

namespace Tests\Feature;

use App\Models\Lead;
use App\Models\Tenant;
use Illuminate\Foundation\Testing\DatabaseTransactions;
use Tests\TestCase;

class LeadListTest extends TestCase
{
    use DatabaseTransactions;

    public function test_leads_belong_to_their_tenant(): void
    {
        $tenant = Tenant::factory()->create();
        $lead = Lead::factory()->create(['tenant_id' => $tenant->id]);

        $this->assertDatabaseHas('leads', [
            'id' => $lead->id,
            'tenant_id' => $tenant->id,
        ]);
    }

    public function test_guest_cannot_open_the_admin_panel(): void
    {
        $this->get('/admin')->assertRedirect();
    }
}

For API tests (device-token or API-key surfaces), follow tests/Feature/MobileApiTest.php — it shows the project's shape for mobile endpoints: create the tenant/device/user, authenticate the way the real client does, and assert the {"data": …} / {"error": {"message","code"}} envelopes.

Conventions that keep the suite green#

1. DatabaseTransactions on every DB-touching test — no truncation, no ordering dependence.
2. Factories over hand-written arrays — extend an existing factory instead of inventing rows.
3. Assert envelopes, not internals — mobile tests assert the documented error.code values; panel tests assert HTTP status/redirects rather than Filament internals.
4. Bind tenant context when a test touches scoped models, mirroring ApiKeyAuthentication / DeviceAuthenticate behavior.
5. No external network calls — third-party systems are exercised through fakes/stubs (queue sync, mail array, cache array).

Related guides#

• Multi-tenancy & isolation
• Queues, jobs & scheduler
• Security model
• Deployment & server errors