Testing

Testing Strategy

Each repo owns its tests and runs them in its own CI. Tests are organized in three tiers.

Tier 1: Unit tests

Vitest suites, mostly next to the source file (foo.ts and foo.test.ts).

Repo	Examples of what is covered
create-hq	scaffold flow, dependency checks, template fetch
hq-cli	manifest parsing, module registration, strategies, command registration and help catalog
hq-cloud	journal operations, ignore filtering (.hqignore / .hqinclude), vault client
hq-pro	Lambda handler logic with mocked AWS SDK

cd hq-cloud
pnpm test          # npm test in create-hq and hq-deploy

Tier 2: Integration tests

Cross-package and API tests. Examples:

• hq-cloud pnpm run test:integration (builds, then runs the test/ suite with network allowed)
• hq-pro pnpm test:e2e against a deployed stack, and pnpm test:compat (no AWS, no network)

Tier 3: End-to-end tests

Full user journeys:

• Install: npx create-hq ~/test-hq (or --local-template <path> for an unreleased scaffold) creates a working HQ.
• Sync: sign in, provision a company, change a file, run hq sync now, and confirm the change on another machine or in hq-console.
• Desktop: install the app on macOS and Windows, complete onboarding, and confirm background sync.

Manual QA Checklist

create-hq

• npx create-hq prompts for a directory when none is given
• The hq-core scaffold downloads and extracts completely
• Missing required dependencies (Node.js, git) block the install; missing optional ones only warn
• --skip-deps, --skip-cli, --skip-sync, --skip-packages, --minimal, --full, --tag, and --local-template behave as described in create-hq --help

hq-cli

• hq modules add <url> registers the module without cloning
• hq modules sync clones into modules/<name>/ and applies the strategy
• hq modules list shows the module inventory
• hq login completes and caches tokens in ~/.hq/cognito-tokens.json
• hq cloud provision company <slug> makes a company cloud-backed
• hq sync push, hq sync pull, and hq sync now move files in both directions
• hq sync status reports the journal summary
• hq doctor reports hook wiring, runtimes, and connection health

hq-cloud

• Upload reaches the company vault; download matches the original
• Each company’s journal is written to ~/.hq/sync-journal.{slug}.json
• .hqignore patterns are respected
• hq-sync-runner emits ndjson progress events

Infrastructure (hq-pro)

• The stage deploys without errors
• API endpoints return correct responses
• Invalid JWTs are rejected
• One company’s member cannot read another company’s vault

Example unit test (hq-cloud)

import { describe, it, expect } from "vitest";
import { isExpectedIgnore } from "./ignore.js";

describe("isExpectedIgnore", () => {
  it("classifies the root person-settings exclusion as expected", () => {
    expect(isExpectedIgnore("person-settings")).toBe(true);
  });
});

CI Pipeline

Each repo has its own ci.yml (hq-deploy uses test.yml) that runs on pull requests. The pnpm repos install with pnpm install and run their build, typecheck, lint, and test scripts; create-hq and hq-deploy use npm. Check each repo’s workflow for the exact jobs. Tests must pass before merging to that repo’s main.