Testing
Strategy
notifito uses a layered testing approach, from fast unit tests to a full end-to-end loop:
- Unit tests — Pure functions, DTOs, validation logic
- Contract tests — Event payloads tested from both producer and consumer sides
- Integration tests — Per-service HTTP tests against real Postgres and a fake queue
- End-to-end tests — Full loop against Docker Compose in CI
- Widget browser tests — Playwright tests for shadow DOM rendering
Framework
- PHP: Pest 4 (apps), Pest 5 (packages/e2e)
- JavaScript: Playwright (widget)
- HTTP testing: Laravel's
Http::fake()for external calls, real Postgres for database
Running Tests
# 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
- Tests use
RefreshDatabasetrait - Test database:
notifito_core_test,notifito_dispatch_test - No SQLite — JSONB and GIN indexes require real Postgres
External Services
- Provider calls are never made live. Recorded fixtures only.
Http::fake()for all external HTTP calls in dashboard and admin tests
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:
- Valid canonical forms
- Missing required attributes
- Unknown keys
- Type-specific validation (enum options, numeric ranges, date formats)
- Normalisation (bare date → date range, scalar → list for multiple enum)
Writing Tests
Test Conventions
- Use Pest syntax: All tests use Pest PHP syntax
- One assertion per test: Keep tests focused
- Descriptive names: Test names should describe behavior
- Use datasets: For testing multiple similar cases
- Use factories: For creating test data
- Mock external services: Never make real API calls
Unit Test Example
<?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
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
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
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
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
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:
- Round-trip through
toArray()/fromArray() - JSON serialisability (pure JSON, no objects or resources)
- snake_case keys throughout (consumers are not all PHP)
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 File | Coverage |
|---|---|
Tenancy/TenantTest.php | Tenant CRUD, slug uniqueness, domain storage |
Tenancy/ApiKeyTest.php | Key issuance, hashing, lookup, revocation |
Catalog/ItemTypeTest.php | Item type CRUD, schema validation |
Subscription/SubscriptionTest.php | Subscription lifecycle, confirmation |
Matching/SubscriptionMatcherTest.php | Subscription matching engine |
Matching/AttributeNarrowingTest.php | Attribute-based filtering |
Consent/ConsentLedgerTest.php | Append-only consent audit trail |
Outbox/OutboxTest.php | Transactional outbox relay |
Internal/Admin/AuthTest.php | Admin authentication |
Internal/Admin/TenantTest.php | Admin tenant management |
Dispatch
| Test File | Coverage |
|---|---|
Channels/PostmarkEmailDriverTest.php | Email sending, retry, bounce handling |
Templates/TemplateRendererTest.php | Template rendering, variable interpolation |
Delivery/PostmarkWebhookTest.php | Webhook handling |
Delivery/SendHandlersTest.php | Send handler logic |
End-to-End Tests
One test running the entire loop against Docker Compose in CI:
- Widget submits a subscription
- Consumer receives confirmation email (captured by test driver)
- Consumer clicks confirmation link
- Seller pushes availability
- 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:
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:
- Shadow DOM rendering of each attribute type
- Form validation
- Submission flow
- Confirmation/unconfirmation states
Run with:
cd widget
npx playwright test
Seed Tenants
Three seed tenants, chosen to be structurally different:
| Tenant | Item | Attributes |
|---|---|---|
| Sneaker store | Named item | enum size |
| Hotel | None | date_range stay, integer guests |
| Clinic | None | date appointment, enum practitioner |
If all three run the full loop unmodified, "industry-agnostic" is evidence rather than a claim.
CI Pipeline
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