110 lines
5.2 KiB
Markdown
110 lines
5.2 KiB
Markdown
# quality-gates Specification
|
|
|
|
## Purpose
|
|
Define Composer quality scripts, architecture boundaries, PostgreSQL-backed feature tests, and the five blocking CI jobs including browser functional, accessibility and motion coverage.
|
|
|
|
## Requirements
|
|
### Requirement: Standardized Composer test scripts exist
|
|
|
|
The system SHALL expose Composer scripts equivalent to `test:unit`, `test:feature`, `test:browser`, `test`, and `quality` with the composition defined in SPEC §13.9.
|
|
|
|
#### Scenario: Developer runs full quality gate locally
|
|
|
|
- **WHEN** a developer runs `composer quality`
|
|
- **THEN** the command executes static analysis, audits, and the applicable test suites
|
|
|
|
### Requirement: Architecture tests enforce domain boundaries
|
|
|
|
The system SHALL include Pest architecture tests that verify `App\Domain` uses strict types and does not depend on `App\Filament` or `App\Livewire`.
|
|
|
|
#### Scenario: Domain layer violates boundary
|
|
|
|
- **WHEN** code in `App\Domain` imports from `App\Filament` or `App\Livewire`
|
|
- **THEN** the architecture test suite MUST fail
|
|
|
|
### Requirement: CI pipeline blocks merge on five jobs
|
|
|
|
The system SHALL run a CI pipeline with blocking jobs named `static`, `unit`, `feature`, `browser`, and `container` as defined in SPEC §14.1.
|
|
|
|
#### Scenario: Static analysis fails on pull request
|
|
|
|
- **WHEN** a pull request introduces a Pint, PHPStan/Larastan, or Composer audit failure
|
|
- **THEN** the `static` job MUST fail and block merge
|
|
|
|
#### Scenario: Feature tests use PostgreSQL
|
|
|
|
- **WHEN** the `feature` CI job runs integration tests
|
|
- **THEN** the job MUST use PostgreSQL and MUST NOT substitute SQLite
|
|
|
|
### Requirement: Local feature tests use PostgreSQL
|
|
|
|
The system SHALL configure `phpunit.xml` so that the Feature test suite uses PostgreSQL with the same connection parameters as CI (`DB_CONNECTION=pgsql`, host, port, database `amare_test`, credentials). Local feature tests MUST NOT default to SQLite `:memory:`.
|
|
|
|
#### Scenario: Developer runs feature tests locally
|
|
|
|
- **WHEN** a developer runs `composer test:feature` with PostgreSQL available
|
|
- **THEN** tests MUST execute against PostgreSQL
|
|
- **AND** MUST NOT silently fall back to SQLite
|
|
|
|
#### Scenario: Feature tests exercise PostgreSQL-specific types
|
|
|
|
- **WHEN** feature tests persist records with jsonb columns (e.g., `social_links`)
|
|
- **THEN** migrations and constraints MUST be validated against PostgreSQL semantics
|
|
|
|
### Requirement: Browser tests run against FrankenPHP-served application
|
|
|
|
The system SHALL execute browser tests using Pest Browser/Playwright against an application served by FrankenPHP in CI. The `browser` job MUST cover the E2E journeys available in the current phase, automated accessibility checks, motion behavior and smoke checks for public routes (SPEC §13.4, §13.7 and §14.1), without pixel comparison.
|
|
|
|
#### Scenario: Browser job validates served application
|
|
|
|
- **WHEN** the `browser` CI job runs
|
|
- **THEN** tests execute against the built application artifact or equivalent production-like image
|
|
|
|
#### Scenario: Browser job covers functional, accessibility and motion assertions
|
|
|
|
- **WHEN** the `browser` CI job runs
|
|
- **THEN** it MUST execute the functional browser, accessibility, motion and smoke suites
|
|
- **AND** a failing functional assertion or a critical/serious accessibility issue MUST block merge
|
|
|
|
#### Scenario: Browser failures publish diagnostics
|
|
|
|
- **WHEN** a browser test fails in CI
|
|
- **THEN** the job MUST publish application logs and browser logs as diagnostics
|
|
|
|
### Requirement: Quality gate includes npm dependency audit
|
|
|
|
The system SHALL run an npm audit as part of the quality/static gate according to the project policy (SPEC §12.6, §13.9). Audit failure MUST block merge unless an explicit, documented exception exists.
|
|
|
|
#### Scenario: Vulnerable dependency fails static gate
|
|
|
|
- **WHEN** `npm audit` reports a policy-violating vulnerability in production dependencies
|
|
- **THEN** the static/quality gate MUST fail and block merge
|
|
|
|
#### Scenario: Developer runs quality locally with audit
|
|
|
|
- **WHEN** a developer runs `composer quality` (or the documented npm audit step it requires)
|
|
- **THEN** the npm audit MUST execute as part of the gate sequence
|
|
|
|
### Requirement: Domain and Application maintain minimum coverage
|
|
|
|
The CI unit gate SHALL measure code coverage for `App\Domain` and `App\Application` and MUST fail when either namespace falls below 80% (SPEC §13.7). Views, migrations, generated code, and framework code MUST NOT be required to meet this threshold.
|
|
|
|
#### Scenario: Coverage drop below threshold blocks merge
|
|
|
|
- **WHEN** Domain or Application coverage is below 80% on the unit CI job
|
|
- **THEN** the job MUST fail
|
|
|
|
#### Scenario: Coverage ignores non-domain layers
|
|
|
|
- **WHEN** coverage is computed for the gate
|
|
- **THEN** Blade views and migrations MUST NOT be counted toward the Domain/Application threshold
|
|
|
|
### Requirement: Staging deploy job runs only after blocking CI jobs
|
|
|
|
When deploying from `main`, the staging deploy workflow MUST require the five blocking CI jobs (`static`, `unit`, `feature`, `browser`, `container`) to succeed before building/pushing the image and triggering Dokploy (SPEC §14.1, §14.3).
|
|
|
|
#### Scenario: Failed browser job prevents staging deploy
|
|
|
|
- **WHEN** the `browser` CI job fails on `main`
|
|
- **THEN** the staging deploy workflow MUST NOT promote a new image
|