Getting Started for Developers

Dot•requirements gives you lightweight, testable requirements without the maintenance hassle of BDD frameworks. Requirements live as Markdown files in your codebase, and you reference them directly in test descriptions.

What You’ll Get

• Requirements as data — Human-readable Markdown files that tools can parse
• Direct references in tests — Use requirement('REQ-ID') as test descriptions
• Automatic coverage tracking — See which requirements have tests after each run
• No new test framework — Works with Vitest, Jest, Playwright, or any runner that supports setup and teardown

Set Up Your Project

1. Install the package

npm install @popoverai/dotrequirements

pnpm add @popoverai/dotrequirements

yarn add @popoverai/dotrequirements

2. Log in to dot•requirements cloud

dotreq login

This opens a browser to authenticate. Your credentials are stored securely and locally.

If you’d prefer to skip this step, you can use dot•requirements without an account. Just be aware that you won’t be able to sync requirements to the cloud or use MCP tools that require external AI input.

3. Initialize the project

dotreq init

You’ll be prompted to either create a new project or connect to an existing one. Init will:

• Create or update .env.local with your project credentials
• Create a .requirements/ directory with an example file
• Update .gitignore to protect your credentials

4. Pull requirements (if connecting to an existing project)

If you connected to an existing project, pull downloads requirements your team has already created:

dotreq pull

If you created a new project, init already gave you .requirements/example.requirements.md to get started. Take a look — it’s human-readable Markdown with a structured format for the testable bits.

Set Up the Test Harness

Add prepare() and finalize() to your test runner’s global setup and teardown. This enables coverage tracking and improves performance.

// vitest.config.ts
import { defineConfig } from 'vitest/config'
 
export default defineConfig({
  test: {
    globalSetup: './vitest.setup.ts',
  },
})

// vitest.setup.ts
import { prepare, finalize } from '@popoverai/dotrequirements/test'
 
// Named exports: Vitest calls setup() before tests, teardown() after
export function setup() {
  prepare()
}
 
export async function teardown() {
  await finalize()
}

// jest.config.cjs
module.exports = {
  globalSetup: './jest.setup.cjs',
  globalTeardown: './jest.teardown.cjs',
}

// jest.setup.cjs
const { prepare } = require('@popoverai/dotrequirements/test')
 
module.exports = async function setup() {
  prepare()
}

// jest.teardown.cjs
const { finalize } = require('@popoverai/dotrequirements/test')
 
module.exports = async function teardown() {
  await finalize()
}

Write Requirement-Driven Tests

Import requirement() and use it as your test descriptions:

import { requirement } from '@popoverai/dotrequirements/test'
 
describe(requirement('REQ-LOGIN-1'), () => {
  it(requirement('REQ-LOGIN-1.0'), async () => {
    // "Accepts valid credentials"
    await login(validUser)
    expect(page).toHaveURL('/dashboard')
  })
 
  it(requirement('REQ-LOGIN-1.1'), async () => {
    // "Rejects invalid credentials"
    await login(invalidUser)
    expect(page).toHaveText('Invalid email or password')
  })
})

The requirement() function returns the requirement text, so your test explorer shows meaningful descriptions instead of cryptic IDs.

Path Formats

Reference requirements using numeric or label-based paths:

Label paths are case-insensitive and use kebab-case for multi-word labels (edge-case, happy-path).

Run Tests and See Coverage

Run your tests as usual:

npm test

After tests complete, finalize() prints a coverage report:

=== Requirements Coverage Report ===

Total Requirements: 12
Tested Requirements: 8
Untested Requirements: 4
Coverage: 66.7%

✓ Tested Requirements:
  - REQ-LOGIN-1: User can log in with email and password
  - REQ-LOGIN-1.0 (AC): Accepts valid credentials
  - REQ-LOGIN-1.1 (AC): Rejects invalid credentials

✗ Untested Requirements:
  - REQ-CHECKOUT-1: User can complete checkout

====================================

If you’re connected to the cloud, coverage is also synced automatically for team visibility.

Common Questions

Should I commit .requirements/ to Git?

Sure! There’s nothing wrong with committing requirements to Git — it gives you versioned backups. Just remember that dot•requirements cloud is the content authority for coverage tools, MCP integrations, and team visibility. Git sync is optional; cloud sync is strongly recommended.

Can I colocate requirements with my components?

Yes. The test harness finds *.requirements.md files anywhere in your project (not just .requirements/). Follow the pattern you use for tests:

• Tests in __tests__/ → requirements in .requirements/
• Tests with components → requirements can join the party

What about monorepos?

We recommend initializing and invoking dotrequirements at the monorepo root. All packages share the same project and credentials. For details on edge cases, see the CLI reference.

Next Steps

• Set up AI assistance — Run dotreq mcp-setup to configure your coding assistant (Claude Code, Cursor, etc.) with MCP tools for style checking and test review
• Explore the format — See Concepts / Requirements for the full Markdown schema
• Track coverage in the cloud — Your team can see coverage at app.dotrequirements.io 

For AI-first development workflows, see Getting Started for AI-First Builders.