npm-package/TESTING.md
This document describes the testing strategy and how to run tests for the @beads/bd npm package.
npm test)Location: scripts/test.js
Purpose: Quick smoke tests to verify basic installation
Tests:
Run:
npm test
Duration: <1 second
npm run test:integration)Location: test/integration.test.js
Purpose: Comprehensive end-to-end testing of the npm package
Tests:
bd version commandbd --help commandbd init --quietbd createbd list --jsonbd showbd updatebd closebd readyRun:
npm run test:integration
Duration: ~30-60 seconds (downloads binaries)
npm run test:all)Runs both unit and integration tests sequentially.
npm run test:all
All tests passing:
╔════════════════════════════════════════╗
║ Test Summary ║
╚════════════════════════════════════════╝
Total tests: 5
Passed: 5
Failed: 0
✅ All tests passed!
bd init creates .beads directorybd create creates issues with hash IDsbd list returns JSON arraybd show returns issue detailsbd update modifies issue statusbd close closes issuesbd ready finds work with no blockersBefore publishing a new version to npm:
# 1. Update version in package.json
npm version patch # or minor/major
# 2. Run all tests
npm run test:all
# 3. Test installation from local tarball
npm pack
npm install -g ./beads-bd-X.Y.Z.tgz
bd version
# 4. Verify in a fresh project
mkdir /tmp/test-bd
cd /tmp/test-bd
git init
bd init
bd create "Test" -p 1
bd list
# 5. Cleanup
npm uninstall -g @beads/bd
Create .github/workflows/test-npm-package.yml:
name: Test npm Package
on:
push:
paths:
- 'npm-package/**'
pull_request:
paths:
- 'npm-package/**'
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
node-version: [18, 20]
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- name: Run unit tests
run: |
cd npm-package
npm test
- name: Run integration tests
run: |
cd npm-package
npm run test:integration
Create .claude/hooks/session-start.sh:
#!/bin/bash
npm install -g @beads/bd
bd init --quiet
Make executable: chmod +x .claude/hooks/session-start.sh
Start new Claude Code for Web session
Verify:
bd version # Should work
bd list # Should show existing issues
# Install globally
npm install -g @beads/bd
# Verify
which bd
bd version
# Use in any project
mkdir ~/projects/test
cd ~/projects/test
git init
bd init
bd create "First issue" -p 1
bd list
# Add to project
npm install --save-dev @beads/bd
# Use via npx
npx bd version
npx bd init
npx bd create "Issue" -p 1
# First install (downloads binary)
npm install -g @beads/bd
# Uninstall
npm uninstall -g @beads/bd
# Reinstall (should use npm cache)
npm install -g @beads/bd
# Should be faster (no binary download if cached)
Cause: Postinstall script didn't download binary
Fix:
Cause: Binary not executable
Fix:
Cause: Network slow, binary download taking too long
Fix:
Cause: Database format changed or JSONL format incorrect
Fix:
| Area | Coverage |
|---|---|
| Package installation | ✅ Full |
| Binary download | ✅ Full |
| CLI wrapper | ✅ Full |
| Basic commands | ✅ High (8 commands) |
| JSONL sync | ✅ Full |
| Platform detection | ✅ Full |
| Error handling | ⚠️ Partial |
| MCP server | ❌ Not included |
Q: Do I need to run tests before every commit?
A: Run npm test (quick unit tests). Run full integration tests before publishing.
Q: Why do integration tests take so long? A: They download ~17MB binary from GitHub releases. First run is slower.
Q: Can I run tests offline? A: Unit tests yes, integration tests no (need to download binary).
Q: Do tests work on Windows? A: Yes, but integration tests need PowerShell for zip extraction.
Q: How do I test a specific version? A: Update package.json version, ensure GitHub release exists, run tests.