Skip to main content

Tests and verification commands

Start with tests close to the changed code. When changing API contracts or the database, also check their consumers. Not all tests run in the same environment.

Which checks to run​

Run these commands from the repository root.

Changed areaCommandsPrerequisites
All TypeScript workspacesnpm run lint / npm run typecheck / npm run test:lintDependencies installed with npm ci
Shared TypeScript contractsnpm run typecheckDependencies installed with npm ci
Frontendnpm run lint / npm run test:web / npm run buildNode.js
Public-page Worker and landing medianpm run test:worker --workspace @videoq/webnpm run build first
APInpm run test:apiNode.js and the Workers test runtime
DB schemanpm run db:check / npm run db:verifyGenerated migrations
UI interactions and appearancenpm run test:storybook / npm run build:storybookChromium
Documentationnpm run build:docsNode.js; builds English and Japanese

npm test runs API and frontend tests. Python and Storybook tests use separate commands.

TypeScript compiler and ESLint​

All five npm workspaces use the latest stable native TypeScript compiler (currently 7.0.2) for tsc, builds, and type checks. ESLint and tools that import the compiler API use TypeScript 6 through the official @typescript/typescript6 compatibility package. The @typescript/native npm alias supplies tsc; the typescript alias supplies the compatibility API and tsc6. This keeps native compiler upgrades independent of tools that do not yet support the native API.

npm run lint checks API, Web, Docs, demo-video, and trpc, including their scripts and tests. Use npm run lint --workspace @videoq/api to check one workspace. The shared rules are in eslint.shared.mjs; React workspaces also check Hooks, and Web keeps its Fast Refresh and layout import rules. TypeScript files use recommendedTypeChecked, including no-floating-promises, no-misused-promises, and await-thenable. Each workspace has a tsconfig.eslint.json that also includes tests and configuration files; Web's Worker files use their own runtime tsconfig. Explicit parserOptions.project entries keep this coverage separate from production builds, whose tsconfigs intentionally exclude some test and tooling files. Test doubles, type fixtures, and stories retain their existing permissive handling of malformed data and asynchronous mocks; Promise handling rules remain enabled. npm run test:lint verifies that every workspace can run the native compiler and detect lint violations with the compatibility API, rejects floating Promises and async callbacks passed to synchronous handlers, and accepts awaited or caught Promises. It uses real temporary source files and a separate process per workspace so TypeScript programs do not accumulate in memory. CI runs each workspace's lint with its existing checks.

Dependabot groups the compiler and compatibility packages together and permits stable major updates. A new TypeScript syntax feature still requires parser support in typescript-eslint; passing the compiler alone does not prove lint compatibility. Docusaurus's inherited baseUrl is cleared with null, and @site/* is explicitly relative to the Docs workspace, because TypeScript 7 removed baseUrl.

Run selected API unit tests​

npm run test:unit --workspace @videoq/api -- test/rag-agent.test.ts

The API's regular test command runs unit tests followed by Workers runtime tests. To run only the Workers tests:

npm run test:workers --workspace @videoq/api

Database integration tests​

Some tests use real PostgreSQL and pgvector. Tests may be skipped when QUOTA_TEST_DATABASE_URL is unset, so passing unit tests alone does not verify database behavior.

QUOTA_TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:55432/postgres npm run test:api

This uses the default local connection as an example. Use a test database only. Some tests create and clean up databases or schemas, so the connection user also needs permission to create test databases.

Frontend and Storybook​

For example, to check a specific hook:

npm test --workspace @videoq/web -- src/hooks/__tests__/useTags.test.ts

Install Chromium before running Storybook interaction tests:

npm exec --workspace @videoq/web -- playwright install chromium
npm run test:storybook

If you change navigation or parent layouts, also check src/__tests__/App.navigation.test.tsx and the Application/Navigation story.

Python worker​

Create a dedicated virtual environment with Python 3.12 or later. For these commands only, switch to apps/worker/:

cd apps/worker
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest tests/ -q

Worker tests that use the database need a test DATABASE_URL. Check each test's prerequisites as well.

Tests using real models​

For answer-pipeline changes, start with deterministic tests before opting into model calls:

BehaviorFocused tests
Tool selection, scope, and independent questionsapps/api/test/rag-agent.test.ts
Structured output, incremental text, and citation boundariesapps/api/test/structured-answer.test.ts, apps/api/test/answer-content-stream.test.ts
Animation-frame rendering, hidden tabs, completion, and cancellationapps/web/src/lib/__tests__/chatStreamController.test.ts

Separate from normal CI, a test verifies that a model chooses search tools appropriately:

RAG_SELECTION_LIVE=1 npm run test:unit --workspace @videoq/api -- test/rag-agent-selection.live.test.ts

This connects to a real OpenAI-compatible API and incurs usage charges. It reads OPENAI_API_KEY, OPENAI_BASE_URL, and LLM_MODEL from environment variables or the API's .dev.vars. It is not required for first-time setup.

Related: Make your first change, Troubleshooting.

For the paid structured-answer comparison and browser timings, see cutover and verification.