Testing Guide

Test Structure

AltBase tests are organized into three categories:

Type	Tool	Location	What It Tests
Unit tests	cargo test	Inline in Rust crate source files	Individual functions and modules
API end-to-end	Vitest	tests/e2e/specs/*.test.ts	HTTP endpoints against a running server
Dashboard UI e2e	Playwright	apps/dashboard/e2e/*.spec.ts	Browser-based dashboard interactions

There is also a set of live dashboard e2e specs at apps/dashboard/e2e-live/*.spec.ts and legacy JSON-based test cases in e2etestcases/*.json.

Running Unit Tests

Rust unit tests live alongside the source code in each crate. Run the full workspace suite:

cargo test --workspace

To run tests for a specific crate:

cargo test -p atlas-auth
cargo test -p atlas-storage
cargo test -p atlas-workflows

To run a specific test by name:

cargo test -p atlas-auth test_signup_creates_user

Formatting and Lint Checks

These are enforced by CI and should pass before you open a PR:

cargo fmt --all -- --check
cargo clippy --workspace -- -D warnings

Running API End-to-End Tests

API e2e tests use Vitest and run against a live server instance. They cover the full HTTP request lifecycle including authentication, authorization, and database state.

Prerequisites

1. Infrastructure containers running (Postgres, Redis, NATS, Azurite, Nango)
2. AtlasDB server running on http://localhost:3000

Running the Tests

cd tests/e2e
npm install
npm test

Or to run a specific spec file:

npx vitest run specs/auth.test.ts
npx vitest run specs/storage.test.ts

What They Cover

The API e2e specs test the full surface from the feature inventory including:

• Platform signup, login, and JWT validation
• Organization and project CRUD
• API key creation and revocation
• REST CRUD with tenant isolation
• Auth flows (email/password, magic link, OTP, OAuth)
• Storage bucket and object operations
• Realtime WebSocket subscriptions
• Workflow definition, run, and approval lifecycle
• Integration connection management

Running Dashboard UI Tests

Dashboard e2e tests use Playwright to automate browser interactions.

Prerequisites

1. Infrastructure and server running
2. Dashboard dev server running on http://localhost:5173

Install Playwright

cd apps/dashboard
npx playwright install

Run the Tests

npx playwright test

To run a specific spec:

npx playwright test e2e/table-editor.spec.ts

To run in headed mode (visible browser):

npx playwright test --headed

What They Cover

Dashboard e2e specs test:

• Login and signup form validation and redirect behavior
• Project list loading and project creation
• Table editor: row CRUD, inline editing, schema changes
• SQL editor: query execution, result grid, error handling
• Auth management: user list, settings, RLS policy management
• Storage browser: bucket creation, file upload, download, delete
• Project settings: API key management, danger zone
• Setup hub and auth wizard walkthrough
• Shell navigation: sidebar, top bar, org switching

Test Planning Catalogs

The docs/testing/ directory contains comprehensive planning catalogs for future test automation. These were derived from a full code inspection of every route, handler, and client surface.

Integration Test Catalog

File: docs/testing/integration-test-catalog.yaml

Contains 315 test case specifications organized into 11 domain groups:

Domain	Features	Test Cases
Platform Control Plane	Users, orgs, projects, API keys, settings	Signup validation, duplicate rejection, auth enforcement, project isolation
API Engine	SQL, schema, generated REST CRUD	Query isolation, RLS filtering, pagination, conflict behavior
Auth Runtime	Email/password, verification, recovery, OAuth, JWKS	Token rotation, banned accounts, email verification, magic link flows
Auth Management	Auth settings, key rotation, RLS, guided setup	Settings persistence, key rotation, policy CRUD, setup wizard
SSO and Customer Orgs	Customer orgs, end-user SSO, SSO management	Org lifecycle, OIDC/SAML callbacks, identity linking, cross-project isolation
Storage	Buckets, objects, signed URLs, resumable uploads, TUS, policies	Upload/download lifecycle, signed URL expiry, TUS resume after interruption
Realtime and Events	WebSocket, cron, event streams	CDC subscriptions, heartbeat, presence, cron CRUD
Jobs/Search/Analytics/Billing	Background jobs, full-text search, materialized views, Stripe	Job lifecycle, search ranking, analytics aggregation, Stripe webhooks
Integrations	Connections, actions, proxy, templates, webhooks	OAuth callbacks, rate limiting, circuit breaker, webhook delivery
Functions/Triggers/Workflows	Functions, triggers, workflow definitions, runs, approvals	Deploy/invoke, trigger dispatch, DAG progression, approval flow, SSE streaming
Vector/RAG/GraphQL	Embeddings, vector search, knowledge, GraphQL	Embedding generation, hybrid search, RAG citations, GraphQL subscriptions

UI Automation Catalog

File: docs/testing/ui-automation-catalog.yaml

Contains test case specifications for the dashboard frontend:

Dashboard routes covered: authentication, admin projects, org overview, table editor, SQL editor, auth management, storage browser, API docs, logs, project settings, workflows widget, setup hub, shell navigation.

Writing New Tests

API e2e Test Pattern

import { describe, it, expect } from 'vitest'

describe('Feature Name', () => {
  it('should do something specific', async () => {
    const response = await fetch('http://localhost:3000/rest/v1/table', {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
    })

    expect(response.status).toBe(200)
    const data = await response.json()
    expect(data).toHaveLength(1)
  })
})

Dashboard e2e Test Pattern

import { test, expect } from '@playwright/test'

test('should create a new row in table editor', async ({ page }) => {
  await page.goto('/dashboard/org/org_1/project/proj_1/editor')
  await page.click('[data-testid="add-row"]')
  await page.fill('[data-testid="cell-name"]', 'Test Value')
  await page.click('[data-testid="save-row"]')
  await expect(page.locator('text=Test Value')).toBeVisible()
})

Tips for New Tests

• Consult the test catalogs in docs/testing/ for case ideas relevant to the subsystem you changed
• API e2e tests should create their own test data and clean up after themselves
• Dashboard tests should use data-testid attributes for element selection
• Group related assertions in a single test to reduce setup overhead
• Test both success and error paths

CI Pipeline

Tests run automatically on every push and pull request:

Step	What Runs
Rust checks	cargo fmt --check, cargo clippy, cargo test --workspace
Dashboard build	npx tsc --noEmit, npm run build
SDK build	npx tsc --noEmit, npm test
CLI build	npx tsc --noEmit, npm run build

API e2e and Playwright tests run in CI with infrastructure containers spun up via Docker Compose.