Testing

Strategy

notifito uses a layered testing approach, from fast unit tests to a full end-to-end loop:

  1. Unit tests — Pure functions, DTOs, validation logic
  2. Contract tests — Event payloads tested from both producer and consumer sides
  3. Integration tests — Per-service HTTP tests against real Postgres and a fake queue
  4. End-to-end tests — Full loop against Docker Compose in CI
  5. Widget browser tests — Playwright tests for shadow DOM rendering

Framework

Running Tests

bash
# Run all tests for an app

./bin/test apps/core

./bin/test apps/dispatch

./bin/test packages/contracts

Run a specific test file

./bin/test apps/core tests/Feature/Tenancy/TenantTest.php

Run a specific test

./bin/test apps/core --filter="it creates a tenant"

Run widget browser tests

cd widget && npx playwright test

Test Conventions

File Location

Tests live in tests/Feature/ within each app, mirroring the source structure:

apps/core/tests/Feature/

├── Tenancy/

│ ├── TenantTest.php

│ └── ApiKeyTest.php

├── Catalog/

│ └── ItemTypeTest.php

├── Subscription/

│ └── SubscriptionTest.php

└── Matching/

└── MatchingEngineTest.php

Database

External Services

Unit Tests

Matching Engine

The matching engine receives the most tests, by a wide margin. It is tested as a pure function:

(schema, subscription attributes, event attributes) → bool

Table-driven cases across all seven attribute types, both wildcard directions, range containment and date-range overlap edges.

Attribute Validation

The AttributeBagValidator is tested against every type in the closed set:


Writing Tests

Test Conventions

  1. Use Pest syntax: All tests use Pest PHP syntax
  2. One assertion per test: Keep tests focused
  3. Descriptive names: Test names should describe behavior
  4. Use datasets: For testing multiple similar cases
  5. Use factories: For creating test data
  6. Mock external services: Never make real API calls

Unit Test Example

php
<?php

declare(strict_types=1);

use Notifito\Contracts\Catalog\AttributeDefinition;

use Notifito\Contracts\Catalog\AttributeType;

it('exposes exactly the seven types the spec allows', function () {

$values = array_map(fn (AttributeType $t) => $t->value, AttributeType::cases());

expect($values)->toEqualCanonicalizing([

'enum', 'integer', 'decimal', 'date', 'date_range', 'boolean', 'text',

]);

});

it('builds an enum definition from the array form', function () {

$definition = AttributeDefinition::fromArray([

'key' => 'size',

'label' => 'Size',

'type' => 'enum',

'options' => ['40', '41', '42'],

'required' => true,

'matchable' => true,

]);

expect($definition->key)->toBe('size')

->and($definition->type)->toBe(AttributeType::Enum)

->and($definition->options)->toBe(['40', '41', '42']);

});

Feature Test Example

php
<?php

declare(strict_types=1);

use App\Models\Tenant;

use App\Models\User;

use Illuminate\Foundation\Testing\RefreshDatabase;

uses(RefreshDatabase::class);

it('authenticates a seller and returns their tenant', function () {

$tenant = Tenant::factory()->create();

$user = User::factory()->create(['tenant_id' => $tenant->id]);

$response = $this->postJson('/internal/auth/login', [

'email' => $user->email,

'password' => 'password',

]);

$response->assertOk()

->assertJsonStructure(['user', 'tenant']);

});

it('rejects a wrong password', function () {

$user = User::factory()->create();

$response = $this->postJson('/internal/auth/login', [

'email' => $user->email,

'password' => 'wrong-password',

]);

$response->assertStatus(401);

});

Livewire Test Example

php
<?php

declare(strict_types=1);

use App\Livewire\ItemTypeEditor;

use Illuminate\Support\Facades\Http;

use Livewire\Livewire;

beforeEach(function () {

config()->set('notifito.core_url', 'http://core.test');

$this->post('/login', ['email' => 'owner@shop.test', 'password' => 'x']);

});

it('loads an existing item type into the editor', function () {

Http::fake([

'http://core.test/internal/tenants/ten-1/item-types/it-1' => Http::response([

'id' => 'it-1',

'name' => 'Sneaker',

'slug' => 'sneaker',

'schema_version' => 3,

'attribute_schema' => [

['key' => 'size', 'label' => 'Size', 'type' => 'enum',

'options' => ['40', '41'], 'required' => true],

],

]),

]);

Livewire::test(ItemTypeEditor::class, ['ref' => 'it-1'])

->assertSet('name', 'Sneaker')

->assertSet('attributes.0.key', 'size');

});


Mocking

HTTP Mocking

php
use Illuminate\Support\Facades\Http;

// Mock specific endpoints

Http::fake([

'http://core.test/internal/auth/login' => Http::response([

'user' => ['id' => 'u-1', 'name' => 'Owner'],

'tenant' => ['id' => 'ten-1', 'name' => 'Store'],

]),

]);

// Mock all requests

Http::fake(fn ($request) => Http::response(['ok' => true]));

// Assert requests were made

Http::assertSent(fn ($request) => $request->url() === 'http://core.test/...');

Event Mocking

php
use Notifito\Contracts\Bus\FakeEventBus;

$bus = new FakeEventBus();

$bus->publish($event);

// Assert event was published

$bus->assertPublished('availability.received');

// Get all published events

$events = $bus->published('availability.received');

Queue Mocking

php
use Illuminate\Support\Facades\Queue;

Queue::fake();

// Assert job was dispatched

Queue::assertPushed(SendDeliveryJob::class);

Contract Tests

Event payloads in packages/contracts are tested from both the producing and the consuming side:

This is the main benefit a monorepo offers: changing a payload breaks CI rather than production.

Integration Tests

Per-service tests at the HTTP boundary, against real Postgres and a fake queue.

Core

Test FileCoverage
Tenancy/TenantTest.phpTenant CRUD, slug uniqueness, domain storage
Tenancy/ApiKeyTest.phpKey issuance, hashing, lookup, revocation
Catalog/ItemTypeTest.phpItem type CRUD, schema validation
Subscription/SubscriptionTest.phpSubscription lifecycle, confirmation
Matching/SubscriptionMatcherTest.phpSubscription matching engine
Matching/AttributeNarrowingTest.phpAttribute-based filtering
Consent/ConsentLedgerTest.phpAppend-only consent audit trail
Outbox/OutboxTest.phpTransactional outbox relay
Internal/Admin/AuthTest.phpAdmin authentication
Internal/Admin/TenantTest.phpAdmin tenant management

Dispatch

Test FileCoverage
Channels/PostmarkEmailDriverTest.phpEmail sending, retry, bounce handling
Templates/TemplateRendererTest.phpTemplate rendering, variable interpolation
Delivery/PostmarkWebhookTest.phpWebhook handling
Delivery/SendHandlersTest.phpSend handler logic

End-to-End Tests

One test running the entire loop against Docker Compose in CI:

  1. Widget submits a subscription
  2. Consumer receives confirmation email (captured by test driver)
  3. Consumer clicks confirmation link
  4. Seller pushes availability
  5. Consumer receives notification email

It is slow and occasionally irritating, and it is the only test that proves the product exists.

Test Driver

A fake email driver that records outbound messages without sending them:

php
class TestDriver implements ChannelDriver

{

/** @var list<OutboundMessage> */

public array $sent = [];

public function send(OutboundMessage $message): SendResult

{

$this->sent[] = $message;

return new SendResult(status: 'accepted', providerMessageId: 'test-' . Str::random(8));

}

}

Widget Browser Tests

Playwright tests covering:

Run with:

bash
cd widget

npx playwright test

Seed Tenants

Three seed tenants, chosen to be structurally different:

TenantItemAttributes
Sneaker storeNamed itemenum size
HotelNonedate_range stay, integer guests
ClinicNonedate appointment, enum practitioner

If all three run the full loop unmodified, "industry-agnostic" is evidence rather than a claim.

CI Pipeline

yaml
steps:

- name: Build containers

run: docker compose build

- name: Start infrastructure

run: docker compose up -d postgres redis

- name: Install dependencies

run: ./bin/dev composer install --working-dir=packages/contracts && ./bin/dev composer install --working-dir=apps/core && ./bin/dev composer install --working-dir=apps/dispatch

- name: Run contracts tests

run: ./bin/test packages/contracts

- name: Run core tests

run: ./bin/test apps/core

- name: Run dispatch tests

run: ./bin/test apps/dispatch

- name: Run E2E tests

run: docker compose -f docker-compose.yml -f docker-compose.e2e.yml run --rm e2e

- name: Widget tests

run: cd widget && npm ci && npx playwright test