Feature: Sandboxes Monitoring - 2 - Testing Infrastructure (#138)

- [ ] 1: API/State Layer #137 
- [ ] 2: **THIS PR**

Builds upon the API/State Management layer to provide comprehensive test
coverage for all utility functions and data processing logic. Integrates
unit tests into the CI pipeline for early regression detection.

## Key Features

**Comprehensive Unit Test Coverage (104 tests)**
- **Chart utilities** (25 tests) - Data transformation, axis
calculations, tooltip formatting
- **Formatting functions** (47 tests) - Date/time/number formatting
across locales and formats
- **Sandboxes utilities** (17 tests) - Metrics processing and
transformation logic
- **Team metrics calculations** (15 tests) - Step calculations and
aggregation algorithms

**Development & Load Testing**
- `burst.test.ts` - Tests system behavior under sudden load spikes
- `traffic.test.ts` - Tests sustained traffic patterns and performance
- Configurable test scenarios for different usage patterns

**GitHub Actions CI Integration**
- Dedicated `unit-tests` job that runs before integration tests
- Minimal environment setup (no external services required)
- Fast feedback loop (~1 second execution time)
- Cost-efficient CI pipeline (integration tests only run if unit tests
pass)

**Test Infrastructure**
- Supporting UI components needed for testing (chart-utils, tooltips)
- Proper test isolation and mocking strategies
- Enhanced test documentation and examples

## Test Coverage Architecture

### CI Pipeline Flow

```mermaid
graph LR
    subgraph "GitHub Actions"
        Push[Push/PR] --> UnitTests["Unit Tests<br/>104 tests<br/>~1s execution"]
        UnitTests --> |"✅ Pass"| IntegrationTests["Integration Tests<br/>~30s execution"]
        UnitTests --> |"❌ Fail"| Stop[❌ Stop Pipeline]
        IntegrationTests --> |"✅ Pass"| Success[✅ All Tests Pass]
        IntegrationTests --> |"❌ Fail"| Fail[❌ Integration Failure]
    end

    subgraph "Test Categories"
        UnitTests --> ChartUtils["Chart Utils (25)"]
        UnitTests --> Formatting["Formatting (47)"]
        UnitTests --> Sandboxes["Sandboxes (17)"]
        UnitTests --> Metrics["Team Metrics (15)"]
    end

    style UnitTests fill:#e1f5fe
    style IntegrationTests fill:#e8f5e9
    style Success fill:#c8e6c9
    style Fail fill:#ffcdd2
    style Stop fill:#ffcdd2
```

### Test Coverage Map

```mermaid
graph TB
    subgraph "Utility Functions Tested"
        subgraph "Chart Utilities"
            CalcAvg["calculateAverage()"]
            CalcMedian["calculateMedian()"]
            CalcCentralTendency["calculateCentralTendency()"]
            CalcYAxis["calculateYAxisMax()"]
            FillZeros["fillMetricsWithZeros()"]
            TransformData["transformMetricsToLineData()"]
            CreateSeries["createChartSeries()"]
        end
        
        subgraph "Formatting Functions"
            FormatNumber["formatNumber()"]
            FormatBytes["formatBytes()"]
            FormatDuration["formatDuration()"]
            FormatDate["formatChartTimestamp*()"]
            FormatCompact["formatCompactNumber()"]
            FormatDecimal["formatDecimal()"]
            FormatPercentage["formatPercentage()"]
        end
        
        subgraph "Data Processing"
            TransformMetrics["transformMetricsToClientMetrics()"]
            CalcStep["calculateStepForDuration()"]
            FillTeamMetrics["fillTeamMetricsWithZeros()"]
        end
    end

    subgraph "Test Files"
        ChartTests["chart-utils.test.ts<br/>25 tests"]
        FormatTests["formatting.test.ts<br/>47 tests"] 
        SandboxTests["sandboxes.test.ts<br/>17 tests"]
        MetricsTests["team-metrics-step.test.ts<br/>15 tests"]
    end

    ChartTests --> CalcAvg
    ChartTests --> CalcMedian
    ChartTests --> CalcCentralTendency
    ChartTests --> CalcYAxis
    ChartTests --> FillZeros
    ChartTests --> TransformData
    ChartTests --> CreateSeries

    FormatTests --> FormatNumber
    FormatTests --> FormatBytes
    FormatTests --> FormatDuration
    FormatTests --> FormatDate
    FormatTests --> FormatCompact
    FormatTests --> FormatDecimal
    FormatTests --> FormatPercentage

    SandboxTests --> TransformMetrics
    SandboxTests --> CalcStep
    
    MetricsTests --> FillTeamMetrics

    style ChartTests fill:#e1f5fe
    style FormatTests fill:#fff3e0
    style SandboxTests fill:#e8f5e9
    style MetricsTests fill:#f3e5f5
```

## Technical Implementation

**Test Architecture**
- Vitest as the test runner with TypeScript support
- Tests focus on pure functions and data transformations
- Mock data generation for consistent test scenarios
- Comprehensive edge case coverage (empty data, boundary conditions,
timezone handling)

**Key Test Files**
- `src/__test__/unit/chart-utils.test.ts` - Chart calculation logic
- `src/__test__/unit/formatting.test.ts` - All formatting utilities
- `src/__test__/unit/sandboxes.test.ts` - Data transformation functions
- `src/__test__/unit/team-metrics-step.test.ts` - Time interval
calculations
- `src/__test__/development/` - Load and performance testing

**CI Pipeline Enhancements**
- Unit tests run first for fast feedback
- Integration tests depend on unit test success
- Parallel test execution for optimal performance
- Clear separation of test types and responsibilities

---
*This PR provides comprehensive test coverage for the API/State
Management layer. All 104 unit tests pass and are integrated into CI.
The testing infrastructure validates that all utility functions work
correctly and provides confidence for further development. Requires PR1
(API layer) to be merged first.*

Author: ben-fornefeld

.github/workflows/test.yml

@@ -7,9 +7,31 @@ on:
     branches: [main]
 
 jobs:
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+
+    # unit tests don't need environment variables - they test pure functions
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: 1.2.20
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run unit tests
+        run: bun test:unit
+
   integration-tests:
     name: Integration Tests
     runs-on: ubuntu-latest
+    needs: unit-tests  # run after unit tests pass
 
     # these are placeholders which is fine for integration tests
     env:
@@ -35,7 +57,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v1
         with:
-          bun-version: latest
+          bun-version: 1.2.20
 
       - name: Install dependencies
         run: bun install

package.json

@@ -11,32 +11,31 @@
     "lint": "next lint",
     "lint:fix": "next lint --fix",
     "format": "prettier --write .",
-    "<<<<<< Development Tools": "",
+    "prebuild": "bun scripts:check-app-env",
+    "<<<<<<< Development Tools": "",
     "scan:local": "bunx react-scan@latest localhost:3000",
-    "<<<<<< Database": "",
+    "<<<<<<< Database": "",
     "db:migrations:create": "bun run scripts:create-migration",
     "db:migrations:apply": "bun run scripts:apply-migrations",
-    "<<<<<< Gen": "",
+    "<<<<<<< Gen": "",
     "generate:infra": "bunx openapi-typescript ./spec/openapi.yaml -o ./src/types/infra-api.d.ts",
     "generate:supabase": "bunx supabase@latest gen types typescript --schema public > src/types/database.types.ts --project-id $SUPABASE_PROJECT_ID",
-    "<<<<<< Scripts": "",
+    "<<<<<<< Scripts": "",
     "scripts:check-app-env": "bun scripts/check-app-env.ts",
     "scripts:check-e2e-env": "bun scripts/check-e2e-env.ts",
     "scripts:check-all-env": "bun scripts:check-app-env && bun scripts:check-e2e-env",
     "scripts:create-migration": "bun scripts/create-migration.ts",
-    "<<<<<< Development": "",
+    "<<<<<<< Development": "",
     "shad": "bunx shadcn@canary",
-    "prebuild": "bun scripts:check-app-env",
-    "<<<<<< Testing": "",
+    "test:development:traffic": "vitest run src/__test__/development/traffic.test.ts",
+    "<<<<<<< Testing": "",
     "test:run": "bun scripts:check-all-env && vitest run",
     "test:integration": "bun scripts:check-app-env && vitest run src/__test__/integration/",
-    "test:unit": "bun scripts:check-app-env && vitest run src/__test__/unit/",
+    "test:unit": "vitest run src/__test__/unit/",
     "test:e2e": "bun scripts:check-all-env && vitest run src/__test__/e2e/",
     "test:watch": "bun scripts:check-all-env && vitest",
     "test:ui": "bun scripts:check-all-env && vitest --ui",
-    "test:ui:integration": "bun scripts:check-app-env && vitest --ui src/__test__/integration/",
-    "test:development:burst": "vitest run src/__test__/development/burst.test.ts",
-    "test:development:traffic": "vitest run src/__test__/development/traffic.test.ts"
+    "test:ui:integration": "bun scripts:check-app-env && vitest --ui src/__test__/integration/"
   },
   "dependencies": {
     "@fumadocs/mdx-remote": "^1.2.0",

src/__test__/README.md

@@ -1,9 +1,43 @@
 # Testing Strategy
 
-This project uses a comprehensive testing strategy with different types of tests for different purposes. This README explains the current state of testing and how to extend it.
-
 ## Current Test Types
 
+### Unit Tests
+
+Unit tests are the most granular tests that verify individual functions, components, or modules work correctly in isolation. These tests are fast, focused, and should be the foundation of our testing pyramid.
+
+**Location:** `src/__test__/unit/`
+
+**Naming Convention:** Unit test files should follow the pattern `[module-name].test.[ext]`
+- For testing `src/lib/utils/formatting.ts`, create `src/__test__/unit/formatting.test.ts`
+- For testing `src/ui/primitives/button.tsx`, create `src/__test__/unit/button.test.tsx`
+- Group related tests in the same file when they test the same module
+
+**Run with:** 
+- All unit tests: `bun test:unit`
+- All tests: `bun test:run`
+- Watch mode: `bun test:watch`
+- Specific file: `bun test src/__test__/unit/formatting.test.ts`
+
+**Examples:**
+- `src/__test__/unit/formatting.test.ts` for testing formatting utilities
+- `src/__test__/unit/auth-utils.test.ts` for testing authentication utilities
+- `src/__test__/unit/button.test.tsx` for testing button component
+
+**Benefits of Centralized Unit Tests:**
+- All unit tests in one location for easy discovery
+- Clear separation between test types
+- Consistent test organization
+- Easy to run all unit tests at once
+
+**What to Unit Test:**
+- Pure utility functions (e.g., formatters, validators, parsers)
+- Business logic functions
+- React hooks
+- Component rendering and behavior
+- Data transformations
+- Error handling edge cases
+
 ### Integration Tests
 
 Integration tests verify that different parts of the application work together correctly, but they use mocks for external dependencies like databases and APIs. These tests are fast, reliable, and don't require external services to be running.
@@ -18,10 +52,6 @@ The integration tests use a dummy environment set in `vitest.config.ts` which pr
 - Integration tests run the `scripts:check-app-env` script before execution to ensure all required application environment variables are set.
 - This is configured in `package.json`: `"test:integration": "bun scripts:check-app-env && vitest run src/__test__/integration/"`
 
-**Examples:**
-- Authentication tests in `src/__test__/integration/auth.test.ts`
-- Middleware tests in `src/__test__/integration/middleware.test.ts`
-
 ### End-to-End (E2E) Tests
 
 **Current Status:** E2E tests are not yet implemented. There is a placeholder file at `src/__test__/e2e/placeholder.test.ts`.
@@ -42,9 +72,6 @@ Development tests are specialized tests designed to assist with feature developm
 
 **Purpose:** These tests spawn real resources (like sandboxes) that can be observed in the dashboard while developing features, eliminating the need to manually manage test resources.
 
-**Examples:**
-- `metrics.test.ts`: Spawns stressed sandboxes in batches to test dashboard performance and metrics visualization
-
 **Environment Setup:**
 To run development tests, you must create a `.env.test` file with the required environment variables:
 ```bash
@@ -60,11 +87,22 @@ TEST_E2B_TEMPLATE=base  # optional, defaults to 'base'
 
 ### Locally
 
-To run all tests:
+To run all tests (unit, integration, and E2E):
 ```bash
 bun test:run
 ```
 
+To run tests in watch mode (great for development):
+```bash
+bun test:watch
+```
+
+To run only unit tests:
+```bash
+bun test:unit
+bun test src/__test__/unit/formatting.test.ts  # specific unit test file
+```
+
 To run only integration tests:
 ```bash
 bun test:integration
@@ -77,7 +115,10 @@ bun test:e2e
 
 ### In CI/CD
 
-Currently, only integration tests are configured to run in CI/CD:
+Currently, unit and integration tests are configured to run in CI/CD:
+- **Unit tests** are run from `src/__test__/unit/`
+- **Integration tests** are run from `src/__test__/integration/`
+- Both use the `.test.` naming convention for automatic discovery
 
 (See [`.github/workflows/test.yml`](.github/workflows/test.yml))
 
@@ -121,9 +162,12 @@ To start implementing E2E tests:
 
 ## Best Practices
 
-1. **Write integration tests for most functionality**: They're faster and more reliable.
-2. **Use E2E tests for critical paths**: Focus on key user journeys like authentication, payment, etc.
-3. **Keep E2E tests minimal**: They're slower and more brittle, so use them sparingly.
-4. **Use test data**: Create and clean up test data in your E2E tests to avoid polluting your development/production environment.
-5. **Skip E2E tests if environment variables are missing**: This allows the tests to be run in environments without the necessary credentials. 
+1. **Start with unit tests**: Write unit tests for all utility functions, pure logic, and isolated components.
+2. **Organize tests by type**: Keep unit tests in `src/__test__/unit/`, integration tests in `src/__test__/integration/`.
+3. **Write integration tests for feature flows**: Test how different parts work together, but mock external dependencies.
+4. **Use E2E tests for critical paths**: Focus on key user journeys like authentication, payment, etc.
+5. **Keep E2E tests minimal**: They're slower and more brittle, so use them sparingly.
+6. **Use test data**: Create and clean up test data in your E2E tests to avoid polluting your development/production environment.
+7. **Skip E2E tests if environment variables are missing**: This allows the tests to be run in environments without the necessary credentials.
+8. **Follow the naming convention**: Always use `.test.` in the filename for all test files.