🧪 Testing Guide

📋 Overview

Metric	Value
Test Framework	Vitest
Environment	happy-dom
Total Tests	155
Test Files	9
Coverage	91%

🚀 Quick Start

# Run tests in watch mode
npm run test

# Run tests once
npm run test:run

# Run with coverage
npm run test:coverage

📁 Test Structure

__tests__/
├── helpers/
│   └── setup.ts                    # Mock factories and utilities
├── navigationRegistry.test.ts      # Registry CRUD (12 tests)
├── navigationOutposts.test.ts      # Patrol logic (19 tests)
├── navigationCitadel.test.ts       # Public API (29 tests)
├── timeout.test.ts                 # Timeout handling (7 tests)
├── lazy.test.ts                    # Lazy loading (12 tests)
├── integration.test.ts             # Full navigation flows (13 tests)
├── devtools-settings.test.ts       # DevTools settings (19 tests)
├── devtools-inspector.test.ts      # DevTools inspector (19 tests)
└── debugHandler.test.ts            # Debug handler (12 tests)

🔧 Test Helpers

Located in __tests__/helpers/setup.ts:

Helper	Description
createMockRouter(routes?)	Creates vue-router with memory history
createMockLogger()	Logger that captures calls for assertions
createAllowHandler()	Returns 'allow' verdict
createBlockHandler()	Returns 'block' verdict
createRedirectHandler(to)	Returns redirect location
createDelayedHandler(ms, outcome)	Async handler with delay (for timeout tests)
createErrorHandler(message)	Throws error with message
createRegisteredOutpost(options)	Creates RegisteredNavigationOutpost for tests — accepts name, handler, priority, hooks, timeout, lazy, onError, onTimeout

Example Usage

import { createMockRouter, createMockLogger, createAllowHandler } from './helpers/setup';

const router = createMockRouter();
const logger = createMockLogger();

// After test, check logger calls
expect(logger.calls.some((c) => c.level === 'warn')).toBe(true);

✍️ Writing New Tests

Choose the Right File

If testing...	Add to...
Registry functions	navigationRegistry.test.ts
Outcome/patrol logic	navigationOutposts.test.ts
Public API	navigationCitadel.test.ts
Timeout behavior	timeout.test.ts
Lazy loading	lazy.test.ts
Full navigation flows	integration.test.ts
DevTools settings	devtools-settings.test.ts
DevTools inspector	devtools-inspector.test.ts
Debug handler/logger	debugHandler.test.ts

Use Existing Helpers

import { describe, it, expect, beforeEach } from 'vitest';
import { createMockRouter, createMockLogger } from './helpers/setup';

describe('myFeature', () => {
  let router: ReturnType<typeof createMockRouter>;
  let logger: ReturnType<typeof createMockLogger>;

  beforeEach(async () => {
    router = createMockRouter();
    logger = createMockLogger();
    await router.push('/');
    await router.isReady();
  });

  it('does something', () => {
    // test code
  });
});

Test Patterns

Testing navigation blocks:

await router.push('/dashboard').catch(() => {});
expect(router.currentRoute.value.name).toBe('home'); // stayed on home

Testing redirects (avoid infinite loops):

handler: ({ to }) => {
  if (to.name !== 'login') return { name: 'login' };
  return 'allow';
};

Testing logger calls:

expect(logger.calls.some((c) => c.level === 'warn' && c.args[0].includes('timed out'))).toBe(true);

📝 Test Cases

See the complete Test Cases Reference for a full list of all 155 tests across 9 test files.

---

📊 Coverage

Run coverage report:

npm run test:coverage

Coverage includes all files in src/ except index.ts (re-exports only).