Unit Testing & Coverage Boundaries

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/check.test.ts
• packages/core/src/statuspage-webhook.test.ts
• packages/core/src/feed.test.ts
• ARCHITECTURE.md
• codecov.yml
• CLAUDE.md

The StatusBeam testing strategy is designed around a strict architectural hierarchy. Testing is concentrated in the Domain Layer (packages/core), which contains the framework-free logic responsible for service monitoring, status derivation, and configuration validation. This approach ensures that the most critical business logic is safe to refactor while maintaining high confidence in the system's core stability.

The project utilizes bun test as its primary test runner, with coverage gates enforced during CI/CD. Coverage is explicitly scoped to capture domain-intensive modules while intentionally excluding infrastructure-heavy "glue code" that is better validated through integration or manual deployment.

Sources: ARCHITECTURE.md:167-172, CLAUDE.md:21-25

Testing Architecture and Toolchain

StatusBeam employs a monorepo structure where testing tools and configurations are centralized at the root but executed per workspace.

Core Tooling

• Test Runner: bun test.
• Coverage Engine: Native Bun coverage, outputting text and lcov formats.
• CI Integration: GitHub Actions runs tests with a JUnit reporter for SonarCloud and Codecov integration.
• Reporting: Coverage data is uploaded to Codecov and SonarCloud, with a patch target of 80% for new or changed lines.

Sources: ARCHITECTURE.md:167-172, codecov.yml:2-10, CLAUDE.md:21-25

Coverage Flow Diagram

This diagram illustrates how test results and coverage data flow from local execution to CI reporting tools.

Coverage Boundaries

The project defines clear boundaries for what must be tested and what is excluded from coverage metrics.

High-Coverage Zones (packages/core)

The packages/core module is the most well-tested area, containing approximately 110 cases across 8 files. Key tested components include:

• Status Derivation: Mapping HTTP codes and response times to "up", "degraded", or "down".
• Adapters: Validating logic for Statuspage, incident.io, and Sentry monitors.
• Feeds: Ensuring Atom/RSS feeds are correctly escaped and sorted.
• Webhooks: Validating real-time ingest schemas and status extraction.

Sources: ARCHITECTURE.md:158-166, packages/core/src/check.test.ts:25-45, packages/core/src/feed.test.ts:31-40

Excluded "Glue Code"

The following areas are excluded from coverage enforcement because they consist primarily of I/O glue, orchestration, or framework-specific boilerplate:

• apps/worker/: Glue logic for D1/KV aggregation and cron orchestration.
• apps/web/: Astro components and SSR middleware (validated via astro check).
• packages/cli/: Command dispatching, prompts, and filesystem scaffolding.
• scripts/: Deployment orchestration and regex-based config splicing.

Sources: ARCHITECTURE.md:173-181, codecov.yml:15-23

Technical Implementation of Unit Tests

Status and Check Logic

Tests for checkSite and deriveStatus use mock fetch implementations to verify how the system handles various network conditions and status codes.

Function	Test Focus	Relevant File
deriveStatus	Validates thresholds for up, degraded (latency), and down (codes).	check.test.ts
checkSite	Handles request throws, network failures (code 0), and successful fetches.	check.test.ts
statuspageSummaryUrl	Validates URL normalization for vendor API endpoints.	check.test.ts

Sources: packages/core/src/check.test.ts:25-60

Webhook and Schema Validation

The statuspage-webhook.test.ts file focuses on the resilience of real-time ingestions using zod schemas.

Feed Generation and Escaping

Tests for RSS and Atom feeds ensure that the status page can safely expose history to machines without XML injection risks.

• XML Escaping: Verifies that title, page name, and update bodies are escaped for five predefined entities.
• Sorting: Ensures incidents are ordered by the most recent update timestamp, falling back to resolvedAt or startedAt.
• Robustness: Handles unparseable dates by falling back to the Unix epoch rather than throwing errors.

Sources: packages/core/src/feed.test.ts:31-60, packages/core/src/feed.test.ts:100-115

Summary

The "Unit Testing & Coverage Boundaries" of StatusBeam prioritize the stability of the core domain logic. By isolating framework-free functions in packages/core and subjecting them to rigorous testing (over 100 cases), the project maintains high reliability where it matters most—the status derivation and data contracts. Infrastructure and UI layers are intentionally omitted from coverage metrics, favoring integration-level validation through deployment scripts and framework-specific tooling.

Sources: ARCHITECTURE.md:158-185, codecov.yml:12-23