Skip to content

AGENTS.md

Latest commit

 

History

History
69 lines (48 loc) · 2.51 KB

AGENTS.md

File metadata and controls

69 lines (48 loc) · 2.51 KB

Braintrust JavaScript SDK Monorepo

TypeScript SDKs and integrations for Braintrust. Uses pnpm workspaces.

Repository Structure

.
├── js/             # Main `braintrust` package
├── integrations/   # Integration packages (@braintrust/*)
├── e2e/            # End-to-end scenario tests (mock server + subprocess isolation)
├── docs/           # Docs and reference material
└── internal/       # Internal test fixtures and golden projects

Setup

mise install        # Install toolchain and dependencies

Build

pnpm run build      # Build all workspace packages (from repo root)

Testing

Uses Vitest. Prefer running the narrowest relevant test rather than the full suite.

From js/ directory:

pnpm test                         # Core vitest suite (excludes wrappers)
pnpm test -- -t "test name"       # Filter by test name
pnpm run test:checks              # Hermetic tests (core + vitest wrapper)

E2E tests (e2e/):

Each scenario runs the SDK in a subprocess against a mock Braintrust server and snapshots the results. No API keys required for replay; recording needs provider keys.

pnpm run test:e2e                 # Run all e2e scenarios (from repo root)
pnpm run test:e2e:update          # Update e2e snapshots without re-recording cassettes
pnpm run test:e2e:record          # Re-record provider cassettes and update snapshots

When adding or modifying e2e tests, run the relevant e2e verification twice before stopping so flakes are caught proactively. After running pnpm run test:e2e:update or pnpm run test:e2e:record, always run the normal e2e tests afterward to verify there is no snapshot drift or unstable output.

Span-tree snapshots are paired: *.span-tree.json is the structural contract, and *.span-tree.txt is the human-readable ASCII tree generated from the same normalized spans. Both files are asserted and should be updated together through pnpm run test:e2e:update or pnpm run test:e2e:record; do not hand-edit only one side of the pair.

From repo root:

pnpm run test       # Run all workspace tests via turbo

Linting & Formatting

Run from the repo root. Always run fix:formatting before committing — there is a pre-commit hook that will reject unformatted code.

pnpm run formatting      # Check formatting (prettier)
pnpm run lint            # Run eslint checks
pnpm run fix:formatting  # Auto-fix formatting
pnpm run fix:lint        # Auto-fix eslint issues