Testing Guide

Test setup

Exowpee uses PHPUnit for testing. Configuration is in phpunit.xml. Run the commands below from the project root, with the Docker app and db services running. The full suite uses four processes and a separate test database for each process. Filtered runs use one parallel process, which still gets its own <DB_DATABASE>_test_1 database. The app container exports .env (env_file), so a plain serial artisan test would otherwise target the development database from .env. tests/TestCase.php refuses to run tests that use a Laravel database trait (RefreshDatabase, DatabaseTransactions, DatabaseMigrations, DatabaseTruncation) unless the target database name contains test; keep --parallel for filtered runs, or set DB_DATABASE to a dedicated test database. Tests that must commit for real (row locks seen from a second connection, migrations replayed in a temporary schema) cannot use RefreshDatabase’s transaction. They use Tests\Support\UsesTestDatabaseWithoutTransactions (included by IsolatedOrganizationSchema), which builds on DatabaseTruncation: they get the same per-process test database and guard, and write only into temporary schemas they drop. Tests without any database trait must not touch the database.

Running tests

The memory limit of each ParaTest worker comes from phpunit.xml (memory_limit), not from the -d flag of the parent command, which does not reach the workers. Raise it there if a full run dies with Allowed memory size ... exhausted.

# Run all tests
docker compose exec app php -d memory_limit=1G artisan test --parallel --processes=4 --recreate-databases

# Run a specific test file
docker compose exec app php artisan test --parallel --processes=1 --filter=OrderTest

# Run tests in a specific directory
docker compose exec app php artisan test --parallel --processes=1 tests/Feature/

Test structure

tests/
├── Feature/              # Integration tests (HTTP, database)
│   ├── ExampleTest.php
│   ├── MergeTest.php
│   └── PointOfSaleTest.php
├── Unit/                 # Unit tests (isolated logic)
│   └── ExampleTest.php
└── TestCase.php          # Base test class

Writing a feature test

Feature tests make HTTP requests and assert on responses:

<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;

class ProductTest extends TestCase
{
    use RefreshDatabase;

    public function test_can_list_products(): void
    {
        // Arrange: create a user and authenticate
        $user = User::factory()->create();
        $token = auth()->login($user);

        // Act: make the request
        $response = $this->withHeaders([
            'Authorization' => "Bearer $token",
        ])->getJson('/v1/catalog/products');

        // Assert: check the response
        $response->assertStatus(200)
                 ->assertJsonStructure([
                     'data' => [['id', 'title', 'type', 'status']],
                 ]);
    }

    public function test_can_create_product(): void
    {
        $user = User::factory()->create();
        $token = auth()->login($user);

        $response = $this->withHeaders([
            'Authorization' => "Bearer $token",
        ])->postJson('/v1/catalog/products', [
            'title'    => 'Test Product',
            'type'     => 'physical',
            'status'   => 'active',
            'variants' => [
                ['sku' => 'TEST-001', 'price' => 10000],
            ],
        ]);

        $response->assertStatus(201)
                 ->assertJson(['title' => 'Test Product']);
    }

    public function test_unauthorized_user_cannot_create_product(): void
    {
        $user = User::factory()->create(); // User without create permission
        $token = auth()->login($user);

        $response = $this->withHeaders([
            'Authorization' => "Bearer $token",
        ])->postJson('/v1/catalog/products', [
            'title' => 'Test',
            'type'  => 'physical',
        ]);

        $response->assertStatus(403);
    }
}

Writing a unit test

Unit tests test individual classes in isolation:

<?php

namespace Tests\Unit;

use Tests\TestCase;
use Exowpee\Shared\Traits\KsuidTrait;

class KsuidTest extends TestCase
{
    public function test_generates_valid_ksuid(): void
    {
        $model = new class extends \Illuminate\Database\Eloquent\Model {
            use KsuidTrait;
        };

        $ksuid = $model->generateKsuid();
        $this->assertEquals(27, strlen($ksuid));
    }
}

Factories

Model factories live in database/factories/:

Factory	Model
`UserFactory`	Creates test users
`PointOfSaleFactory`	Creates POS test data
`ExternalTransferFactory`	Creates transfer test data
`NotificationFactory`	Creates notification test data

Testing with database

Use RefreshDatabase trait to reset the database between tests:

use Illuminate\Foundation\Testing\RefreshDatabase;

class MyTest extends TestCase
{
    use RefreshDatabase;
}

Testing tips

Always test authorization — Verify that unauthorized users get 403
Test validation — Send invalid data and check for 422 errors
Test multi-tenancy — Verify users can’t access other companies’ data
Use factories — Don’t create test data manually
Test side effects — Verify that stock changes, ledger entries, and events fire correctly

Getting started

Architecture

Developer guide

Operations

More

Testing Guide

Test setup

Running tests

Test structure

Writing a feature test

Writing a unit test

Factories

Testing with database

Testing tips

​Test setup

​Running tests

​Test structure

​Writing a feature test

​Writing a unit test

​Factories

​Testing with database

​Testing tips

Test setup

Running tests

Test structure

Writing a feature test

Writing a unit test

Factories

Testing with database

Testing tips