stonks-oracle/.kiro/specs/integration-test-pipeline/requirements.md

Integration Test Pipeline — Requirements

Overview

End-to-end integration test pipeline that runs in Kubernetes, spinning up isolated infrastructure (PostgreSQL, Redis, MinIO), seeding realistic data, deploying all application services, and validating every frontend page's data dependencies against live API responses. Includes profiling for performance optimization.

Functional Requirements

FR-1: Pipeline Stages

1. Lint — ruff check on Python, eslint on frontend
2. Unit Tests — pytest + vitest against local mocks
3. Build — Docker images for all services + dashboard
4. Deploy Sandbox — ephemeral namespace with own PostgreSQL, Redis, MinIO (no Ollama — too heavy for CI)
5. Seed Data — populate DB and S3 with enough data to exercise every frontend component
6. Integration Tests — HTTP-level validation of every API endpoint the frontend depends on
7. Frontend E2E — render every page against the live sandbox APIs, assert no errors and expected data
8. Profiling — measure and report timing for each pipeline stage and each API endpoint
9. Teardown — delete the ephemeral namespace and all resources

FR-2: Sandbox Infrastructure

• PostgreSQL 16 (ephemeral, no persistent volume)
• Redis 7 (ephemeral)
• MinIO (ephemeral, with bucket initialization)
• All application services (query-api, symbol-registry, risk, trading-engine) running against sandbox infra
• No Ollama — LLM-dependent services (extractor, recommendation thesis rewriter) are excluded from integration tests
• No Trino/Hive/Superset — analytical stack excluded (not needed for frontend validation)

FR-3: Seed Data Coverage

The seed data must exercise every frontend page. Minimum:

• 5 companies with sources, aliases, competitor relationships
• 10 documents (mix of news, filings, macro_event) with intelligence extraction records
• 5 trend windows with projections and evidence
• 5 recommendations with evidence citations
• 3 orders (filled, pending, cancelled) with events and audit trail
• 2 positions with P&L
• 2 global events with macro impact records across multiple companies
• 2 competitive signal records
• 2 historical pattern records
• 1 trading engine config + 1 trading decision
• 1 portfolio snapshot
• 3 AI agents with 1 variant each + performance log entries
• 1 risk config with macro_enabled and competitive_enabled
• MinIO buckets with at least 1 object in stonks-normalized

FR-4: API Endpoint Validation

Test every endpoint the frontend calls:

• Query API (17 endpoints): companies, documents, trends, recommendations, orders, positions, macro events, pipeline health, ingestion summary, coverage gaps, agents, variants
• Symbol Registry (8 endpoints): companies CRUD, sources, aliases, competitors, exposure profiles
• Risk Engine (4 endpoints): evaluate, approvals pending/review, health
• Trading Engine (12 endpoints): status, config, decisions, metrics, backtest, notifications, override

FR-5: Frontend Page Validation

For each of the 17 frontend pages, verify:

• The page renders without JavaScript errors
• All API calls return 200 with non-empty data
• Key data fields are present (e.g., company has ticker, trend has direction)

FR-6: Profiling & Reporting

• Wall-clock time for each pipeline stage
• P50/P95/P99 response times for each API endpoint
• Total seed data insertion time
• Memory usage of each service pod
• Final pass/fail summary with details on any failures

Non-Functional Requirements

NFR-1: Isolation

Each pipeline run uses a unique Kubernetes namespace (stonks-inttest-{run-id}) that is fully cleaned up on completion (success or failure).

NFR-2: Speed

Target: full pipeline completes in under 10 minutes. Seed data insertion under 30 seconds. API validation under 60 seconds.

NFR-3: Reproducibility

Seed data is deterministic (fixed UUIDs, timestamps). No external API calls (Polygon, Alpaca). All data is synthetic.

NFR-4: CI Integration

Pipeline can be triggered from GitHub Actions as a separate workflow, or manually via kubectl apply.