Solution Baseline — Testing Standards

Version: 1.0
Status: Approved
Owner: Platform Engineering / QA
Last Updated: 2026-04-12
References: AGENT.md §13, system.md §8

---

1. Purpose

This document defines the authoritative testing strategy, coverage targets, tooling, and CI gate requirements for all services in the Ghasi Messaging Gateway platform. All teams MUST comply.

---

2. Test Pyramid

         ┌─────────────┐
         │   E2E Tests │  ← Full platform flows; fewest tests
         ├─────────────┤
         │  Contract   │  ← Service boundary contracts
         ├─────────────┤
         │ Integration │  ← NATS, DB, SMPP (mocked) tests
         ├─────────────┤
         │  Unit Tests │  ← Domain logic; most tests
         └─────────────┘

---

3. Test Tiers

3.1 Unit Tests

• Scope: Domain entities, value objects, use cases, pure utility functions.
• Rule: MUST NOT import infrastructure (NestJS, Prisma, NATS, Redis).
• Framework: Vitest (preferred) or Jest.
• Coverage target: Domain layer ≥ 90%, Application layer ≥ 80%.
• Location: src/tests/unit/

3.2 Integration Tests

• Scope: NATS consumers/publishers, Prisma repository implementations, SMPP connector behaviour (mocked operator).
• Rule: May spin up real Postgres and NATS via Docker in CI. SMPP operator MUST be mocked.
• Framework: Vitest + Testcontainers.
• Coverage target: Infrastructure layer ≥ 60%.
• Location: src/tests/integration/

3.3 Contract Tests

• Scope: API Gateway ↔ downstream services; microservices ↔ NATS message schemas.
• Tool: Pact or custom schema-assertion library against OpenAPI 3.1 specs.
• Rule: Provider must publish pacts; consumers must verify against them in CI.
• Location: src/tests/contract/

3.4 End-to-End Tests

• Scope:
  • Full outbound SMS flow: POST /v1/sms/send → Orchestrator → SMPP → DLR → Billing → Webhook.
  • Operator failover flow.
  • Webhook delivery with HMAC verification.
  • Authentication flows (Keycloak SSO default + tenant external OIDC/SAML SSO + API Key + legacy Firebase where still enabled).
• Environment: Dedicated e2e environment with real NATS, Postgres, Redis and a mock SMPP operator.
• Framework: Playwright (for portal UI flows) + custom Node scripts (for API flows).
• Location: tests/e2e/

---

4. Coverage Requirements Summary

Layer	Minimum Coverage
Domain (entities, value objects)	90%
Application (use cases, mappers)	80%
Infrastructure (HTTP, NATS, DB)	60%
E2E critical paths	100% of flows listed in §3.4

---

5. CI Gates (GitHub Actions)

All PRs MUST pass in order:

Step	Description	Failure action
1. Lint	ESLint + TypeScript strict check	Block merge
2. Unit tests	Vitest unit suite	Block merge
3. Integration tests	Vitest + Testcontainers	Block merge
4. Contract tests	Pact verification	Block merge
5. Coverage check	Enforce thresholds per §4	Block merge
6. Build	tsc --noEmit + Docker image build	Block merge
7. E2E tests	Run on e2e environment	Block merge
8. Deploy	Deploy to Kubernetes (production)	Manual approval required

---

6. Environments

Environment	Purpose	SMPP	Database
local	Developer Docker Compose	Mock	Real Postgres
ci	GitHub Actions runners	Mock	Testcontainers
e2e	Dedicated E2E cluster	Mock SMPP server	Real Postgres
staging	Pre-production validation	Real operator (sandbox)	Real Postgres
production	Live traffic	Real operators	Real Postgres

---

7. Test Data Management

• Unit and integration tests MUST use factories or builders — no hardcoded test data.
• E2E tests MUST clean up created resources after each run.
• Test account IDs must use a reserved prefix (e.g. test_acc_*) to prevent cross-environment contamination.
• Production data MUST NEVER be used in non-production environments.

---

8. Observability in Tests

• Integration tests MUST verify that expected Prometheus metrics increment correctly.
• E2E tests MUST verify that OpenTelemetry trace IDs propagate end-to-end.
• Contract tests MUST validate that NATS message schemas include required tracing headers (x-trace-id, x-correlation-id).

---

9. Prohibited Patterns

Pattern	Reason
Testing infrastructure in unit tests	Violates DDD layer isolation (AGENT.md §4.2)
console.log in any test	Noisy CI output; use structured assertions
Skipping tests without a linked issue	Masks regressions
Hard-coded credentials in test code	Security violation (AGENT.md §11.2)
Mocking domain logic in unit tests	Defeats the purpose of domain-layer testing

---

10. Assumptions and Open Points

ID	Assumption / Open Point	Owner	Resolution Date
A-001	Pact broker URL and credentials TBD	QA Team	TBD
A-002	Mock SMPP server implementation to be selected (smpp-simulator vs custom)	SMPP Team	TBD
A-003	Playwright is used for UI E2E; scope limited to critical customer portal and admin flows	QA Team	TBD