tests/
├── unit/                    # Unit tests for individual packages
│   ├── core.test.js        # @ruvector/core tests
│   ├── wasm.test.js        # @ruvector/wasm tests
│   ├── ruvector.test.js    # ruvector main package tests
│   └── cli.test.js         # CLI tests
├── integration/             # Cross-package integration tests
│   └── cross-package.test.js
├── performance/             # Performance benchmarks
│   └── benchmarks.test.js
├── fixtures/                # Test data and fixtures
│   └── temp/               # Temporary test files (auto-cleaned)
├── run-all-tests.js        # Test runner script
├── test-results.json       # Latest test results
└── README.md               # This file

Running Tests

All Tests

# From npm/tests directory
node run-all-tests.js

# Or from npm root
npm test

Unit Tests Only

node run-all-tests.js --only=unit

Integration Tests Only

node run-all-tests.js --only=integration

Performance Benchmarks

node run-all-tests.js --perf

Individual Test Files

# Run specific test file
node --test unit/core.test.js
node --test unit/wasm.test.js
node --test unit/ruvector.test.js
node --test integration/cross-package.test.js

Test Coverage

@ruvector/core (Native Module)

✅ Platform detection (Linux, macOS, Windows)
✅ Architecture detection (x64, arm64)
✅ Native binding loading
✅ VectorDB creation with options
✅ Vector insertion (single and batch)
✅ Vector search with HNSW
✅ Vector deletion and retrieval
✅ Distance metrics (Cosine, Euclidean, etc.)
✅ HNSW configuration
✅ Quantization options
✅ Version and utility functions

@ruvector/wasm (WebAssembly Module)

✅ WASM module loading in Node.js
✅ Environment detection
✅ VectorDB initialization
✅ Vector operations (insert, search, delete, get)
✅ Batch operations
✅ Metadata support
✅ Float32Array and Array support
✅ SIMD detection
✅ Browser vs Node.js compatibility

ruvector (Main Package)

✅ Backend detection and loading
✅ Native vs WASM fallback
✅ Platform prioritization
✅ VectorIndex creation
✅ API consistency across backends
✅ Utils functions (cosine, euclidean, normalize)
✅ TypeScript type definitions
✅ Error handling
✅ Stats and optimization

CLI (ruvector command)

✅ Command availability
✅ Help and version commands
✅ Info command (backend info)
✅ Init command (index creation)
✅ Insert command (batch insert)
✅ Search command
✅ Stats command
✅ Benchmark command
✅ Error handling
✅ Output formatting

Integration Tests

✅ Backend loading consistency
✅ API compatibility between native/WASM
✅ Data consistency across operations
✅ Search result determinism
✅ Error handling consistency
✅ TypeScript types availability

Performance Benchmarks

✅ Insert throughput (single and batch)
✅ Search latency and throughput
✅ Concurrent search performance
✅ Dimension scaling (128, 384, 768, 1536)
✅ Memory usage analysis
✅ Backend comparison
✅ Utils performance

Expected Behavior

Test Skipping

Tests automatically skip when dependencies are unavailable:

@ruvector/core tests: Skipped if native bindings not built for current platform
@ruvector/wasm tests: Skipped if WASM not built (npm run build:wasm required)
CLI tests: Skipped if dependencies not installed

Performance Expectations

Minimum performance targets (may vary by backend):

Insert: >10 vectors/sec (single), >1000 vectors/sec (batch)
Search: >5 queries/sec
Latency: <1000ms average for k=10 searches
Memory: <5KB per vector (with overhead)

Test Results

After running tests, check test-results.json for detailed results:

{
  "timestamp": "2024-01-01T00:00:00.000Z",
  "summary": {
    "total": 5,
    "passed": 5,
    "failed": 0,
    "passRate": "100.0%"
  },
  "results": [...]
}

Prerequisites

For @ruvector/core tests:

# Build native bindings (from project root)
cargo build --release
npm run build:napi

For @ruvector/wasm tests:

# Build WASM (requires wasm-pack)
cd npm/wasm
npm run build:wasm

For all tests:

# Install dependencies for each package
cd npm/core && npm install
cd npm/wasm && npm install
cd npm/ruvector && npm install

Troubleshooting

"Cannot find module" errors

Ensure dependencies are installed: npm install in each package
Build packages first: npm run build in each package

"Native binding not available"

Build Rust crates first: cargo build --release
Check platform support: Currently supports linux-x64, darwin-arm64, etc.

"WASM module not found"

Build WASM: cd npm/wasm && npm run build:wasm
Install wasm-pack: cargo install wasm-pack

Tests timeout

Increase timeout for performance tests
Use --perf flag separately for benchmarks
Run individual test files for debugging

CI/CD Integration

Add to your CI pipeline:

# .github/workflows/test.yml
- name: Run Tests
  run: |
    cd npm/tests
    node run-all-tests.js

Contributing

When adding new features:

Add unit tests in unit/
Add integration tests if it affects multiple packages
Add performance benchmarks if it's performance-critical
Update this README with new test coverage
Ensure all tests pass before submitting PR

License

MIT