beads/npm-package/TESTING.md

Testing the @beads/bd npm Package

This document describes the testing strategy and how to run tests for the @beads/bd npm package.

Test Suites

1. Unit Tests (npm test)

Location: scripts/test.js

Purpose: Quick smoke tests to verify basic installation

Tests:

• Binary version check
• Help command

Run:

npm test

Duration: <1 second

2. Integration Tests (npm run test:integration)

Location: test/integration.test.js

Purpose: Comprehensive end-to-end testing of the npm package

Tests:

Test 1: Package Installation

• Packs the npm package into a tarball
• Installs globally in an isolated test environment
• Verifies binary is downloaded and installed correctly

Test 2: Binary Functionality

• Tests bd version command
• Tests bd --help command
• Verifies native binary works through Node wrapper

Test 3: Basic bd Workflow

• Creates test project with git
• Runs bd init --quiet
• Creates an issue with bd create
• Lists issues with bd list --json
• Shows issue details with bd show
• Updates issue status with bd update
• Closes issue with bd close
• Verifies ready work detection with bd ready

Test 4: Claude Code for Web Simulation

• Session 1: Initializes bd, creates an issue
• Verifies JSONL export
• Deletes database to simulate fresh clone
• Session 2: Re-initializes from JSONL (simulates SessionStart hook)
• Verifies issues are imported from JSONL
• Creates new issue (simulating agent discovery)
• Verifies JSONL auto-export works

Test 5: Platform Detection

• Verifies current platform is supported
• Validates binary URL construction
• Confirms GitHub release has required binaries

Run:

npm run test:integration

Duration: ~30-60 seconds (downloads binaries)

3. All Tests (npm run test:all)

Runs both unit and integration tests sequentially.

npm run test:all

Test Results

All tests passing:

╔════════════════════════════════════════╗
║  Test Summary                          ║
╚════════════════════════════════════════╝

Total tests: 5
Passed: 5
Failed: 0

✅ All tests passed!

What the Tests Verify

Package Installation

• ✅ npm pack creates valid tarball
• ✅ npm install downloads and installs package
• ✅ Postinstall script runs automatically
• ✅ Platform-specific binary is downloaded
• ✅ Binary is extracted correctly
• ✅ Binary is executable

Binary Functionality

• ✅ CLI wrapper invokes native binary
• ✅ All arguments pass through correctly
• ✅ Exit codes propagate
• ✅ stdio streams work (stdin/stdout/stderr)

bd Commands

• ✅ bd init creates .beads directory
• ✅ bd create creates issues with hash IDs
• ✅ bd list returns JSON array
• ✅ bd show returns issue details
• ✅ bd update modifies issue status
• ✅ bd close closes issues
• ✅ bd ready finds work with no blockers

Claude Code for Web Use Case

• ✅ Fresh installation works
• ✅ JSONL export happens automatically
• ✅ Database can be recreated from JSONL
• ✅ Issues survive database deletion
• ✅ SessionStart hook pattern works
• ✅ Agent can create new issues
• ✅ Auto-sync keeps JSONL updated

Platform Support

• ✅ macOS (darwin) - amd64, arm64
• ✅ Linux - amd64, arm64
• ✅ Windows - amd64 (zip format)
• ✅ Correct binary URLs generated
• ✅ GitHub releases have required assets

Testing Before Publishing

Before 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

Continuous Integration

GitHub Actions (Recommended)

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

Manual Testing Scenarios

Scenario 1: Claude Code for Web SessionStart Hook

1. Create .claude/hooks/session-start.sh:

   #!/bin/bash
   npm install -g @beads/bd
   bd init --quiet
   

2. Make executable: chmod +x .claude/hooks/session-start.sh

3. Start new Claude Code for Web session

4. Verify:

   bd version  # Should work
   bd list     # Should show existing issues
   

Scenario 2: Global Installation

# 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

Scenario 3: Project Dependency

# Add to project
npm install --save-dev @beads/bd

# Use via npx
npx bd version
npx bd init
npx bd create "Issue" -p 1

Scenario 4: Offline/Cached Installation

# 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)

Troubleshooting Tests

Test fails with "binary not found"

Cause: Postinstall script didn't download binary

Fix:

• Check GitHub release has required binaries
• Verify package.json version matches release
• Check network connectivity

Test fails with "permission denied"

Cause: Binary not executable

Fix:

• Postinstall should chmod +x on Unix
• Windows doesn't need this

Integration test times out

Cause: Network slow, binary download taking too long

Fix:

• Increase timeout in test
• Use cached npm packages
• Run on faster network

JSONL import test fails

Cause: Database format changed or JSONL format incorrect

Fix:

• Check bd version compatibility
• Verify JSONL format matches current schema
• Update test to use proper operation records

Test Coverage

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

Known Limitations

1. No MCP server tests: The npm package only includes the CLI binary, not the Python MCP server
2. Platform testing: Tests only run on the current platform (need CI for full coverage)
3. Network dependency: Integration tests require internet to download binaries
4. Timing sensitivity: JSONL auto-export has 5-second debounce, tests use sleep

Future Improvements

1. Mock binary downloads for faster tests
2. Cross-platform CI to test on all OSes
3. MCP server integration (if Node.js MCP server is added)
4. Performance benchmarks for binary download times
5. Stress testing with many issues
6. Concurrent operation testing for race conditions

FAQ

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.