Testing Guide

Running tests

# All ~350 tests
pnpm test

# Single package
pnpm --filter @xnet/sync test
pnpm --filter @xnet/data test
pnpm --filter @xnet/canvas test

# Single file
pnpm --filter @xnet/sync vitest run src/clock.test.ts

# Pattern match
pnpm --filter @xnet/data vitest run -t "NodeStore"

# Watch mode
pnpm --filter @xnet/sync test:watch

Test structure

All tests use Vitest with the Arrange-Act-Assert pattern:

import { describe, it, expect } from 'vitest'

describe('ModuleName', () => {
  describe('functionName', () => {
    it('should do expected behavior', () => {
      // Arrange
      const input = createTestData()

      // Act
      const result = functionName(input)

      // Assert
      expect(result).toBe(expected)
    })
  })
})

What to test

Do test:

• Core packages (crypto, identity, sync, data, plugins)
• Pure functions and algorithms
• Edge cases and error paths
• Immutability guarantees

Don’t test:

• UI components (manual testing only)
• Electron app integration
• Styling/layout

Common patterns

Generating test keys

import { generateSigningKeyPair } from '@xnet/crypto'
import { generateIdentity } from '@xnet/identity'

const { publicKey, privateKey } = generateSigningKeyPair()
const { identity, privateKey: signingKey } = generateIdentity()

Test DIDs

// Quick typed DID for tests
const testDID = 'did:key:z6MkTest123' as DID

// Or generate a real one
const { identity } = generateIdentity()

Suppressing console output

vi.spyOn(console, 'error').mockImplementation(() => {})
vi.spyOn(console, 'warn').mockImplementation(() => {})

Immutability checks

it('should not mutate the input', () => {
  const original = createLamportClock('did:key:alice')
  const time = original.time
  tick(original)
  expect(original.time).toBe(time)
})

Where tests live

Test files are colocated with source code:

packages/sync/src/
  clock.ts
  clock.test.ts
  change.ts
  change.test.ts

Or in a __tests__ directory for packages with many test files:

packages/plugins/src/
  __tests__/
    registry.test.ts
    middleware.test.ts
    sandbox.test.ts

Coverage

Tests cover core algorithms and security-critical paths. Each core package has tests for its primary exports. When adding new functionality to a core package, include tests that verify the expected behavior and edge cases.