docs: Restructure MkDocs navigation and remove test migration guide
- Significantly expand and reorganize documentation navigation structure - Add new sections for AI features, speech processing, and development guidelines - Enhance theme configuration with additional MkDocs features - Remove test migration guide from development documentation - Improve documentation organization and readability
This commit is contained in:
jango-blockchained
@@ -1,323 +0,0 @@
|
|||||||
# Migrating Tests from Jest to Bun
|
|
||||||
|
|
||||||
This guide provides instructions for migrating test files from Jest to Bun's test framework.
|
|
||||||
|
|
||||||
## Table of Contents
|
|
||||||
- [Basic Setup](#basic-setup)
|
|
||||||
- [Import Changes](#import-changes)
|
|
||||||
- [API Changes](#api-changes)
|
|
||||||
- [Mocking](#mocking)
|
|
||||||
- [Common Patterns](#common-patterns)
|
|
||||||
- [Examples](#examples)
|
|
||||||
|
|
||||||
## Basic Setup
|
|
||||||
|
|
||||||
1. Remove Jest-related dependencies from `package.json`:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"devDependencies": {
|
|
||||||
"@jest/globals": "...",
|
|
||||||
"jest": "...",
|
|
||||||
"ts-jest": "..."
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Remove Jest configuration files:
|
|
||||||
- `jest.config.js`
|
|
||||||
- `jest.setup.js`
|
|
||||||
|
|
||||||
3. Update test scripts in `package.json`:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"scripts": {
|
|
||||||
"test": "bun test",
|
|
||||||
"test:watch": "bun test --watch",
|
|
||||||
"test:coverage": "bun test --coverage"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Import Changes
|
|
||||||
|
|
||||||
### Before (Jest):
|
|
||||||
```typescript
|
|
||||||
import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
|
|
||||||
```
|
|
||||||
|
|
||||||
### After (Bun):
|
|
||||||
```typescript
|
|
||||||
import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
|
|
||||||
import type { Mock } from "bun:test";
|
|
||||||
```
|
|
||||||
|
|
||||||
Note: `it` is replaced with `test` in Bun.
|
|
||||||
|
|
||||||
## API Changes
|
|
||||||
|
|
||||||
### Test Structure
|
|
||||||
```typescript
|
|
||||||
// Jest
|
|
||||||
describe('Suite', () => {
|
|
||||||
it('should do something', () => {
|
|
||||||
// test
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
// Bun
|
|
||||||
describe('Suite', () => {
|
|
||||||
test('should do something', () => {
|
|
||||||
// test
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Assertions
|
|
||||||
Most Jest assertions work the same in Bun:
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// These work the same in both:
|
|
||||||
expect(value).toBe(expected);
|
|
||||||
expect(value).toEqual(expected);
|
|
||||||
expect(value).toBeDefined();
|
|
||||||
expect(value).toBeUndefined();
|
|
||||||
expect(value).toBeTruthy();
|
|
||||||
expect(value).toBeFalsy();
|
|
||||||
expect(array).toContain(item);
|
|
||||||
expect(value).toBeInstanceOf(Class);
|
|
||||||
expect(spy).toHaveBeenCalled();
|
|
||||||
expect(spy).toHaveBeenCalledWith(...args);
|
|
||||||
```
|
|
||||||
|
|
||||||
## Mocking
|
|
||||||
|
|
||||||
### Function Mocking
|
|
||||||
|
|
||||||
#### Before (Jest):
|
|
||||||
```typescript
|
|
||||||
const mockFn = jest.fn();
|
|
||||||
mockFn.mockImplementation(() => 'result');
|
|
||||||
mockFn.mockResolvedValue('result');
|
|
||||||
mockFn.mockRejectedValue(new Error());
|
|
||||||
```
|
|
||||||
|
|
||||||
#### After (Bun):
|
|
||||||
```typescript
|
|
||||||
const mockFn = mock(() => 'result');
|
|
||||||
const mockAsyncFn = mock(() => Promise.resolve('result'));
|
|
||||||
const mockErrorFn = mock(() => Promise.reject(new Error()));
|
|
||||||
```
|
|
||||||
|
|
||||||
### Module Mocking
|
|
||||||
|
|
||||||
#### Before (Jest):
|
|
||||||
```typescript
|
|
||||||
jest.mock('module-name', () => ({
|
|
||||||
default: jest.fn(),
|
|
||||||
namedExport: jest.fn()
|
|
||||||
}));
|
|
||||||
```
|
|
||||||
|
|
||||||
#### After (Bun):
|
|
||||||
```typescript
|
|
||||||
// Option 1: Using vi.mock (if available)
|
|
||||||
vi.mock('module-name', () => ({
|
|
||||||
default: mock(() => {}),
|
|
||||||
namedExport: mock(() => {})
|
|
||||||
}));
|
|
||||||
|
|
||||||
// Option 2: Using dynamic imports
|
|
||||||
const mockModule = {
|
|
||||||
default: mock(() => {}),
|
|
||||||
namedExport: mock(() => {})
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### Mock Reset/Clear
|
|
||||||
|
|
||||||
#### Before (Jest):
|
|
||||||
```typescript
|
|
||||||
jest.clearAllMocks();
|
|
||||||
mockFn.mockClear();
|
|
||||||
jest.resetModules();
|
|
||||||
```
|
|
||||||
|
|
||||||
#### After (Bun):
|
|
||||||
```typescript
|
|
||||||
mockFn.mockReset();
|
|
||||||
// or for specific calls
|
|
||||||
mockFn.mock.calls = [];
|
|
||||||
```
|
|
||||||
|
|
||||||
### Spy on Methods
|
|
||||||
|
|
||||||
#### Before (Jest):
|
|
||||||
```typescript
|
|
||||||
jest.spyOn(object, 'method');
|
|
||||||
```
|
|
||||||
|
|
||||||
#### After (Bun):
|
|
||||||
```typescript
|
|
||||||
const spy = mock(((...args) => object.method(...args)));
|
|
||||||
object.method = spy;
|
|
||||||
```
|
|
||||||
|
|
||||||
## Common Patterns
|
|
||||||
|
|
||||||
### Async Tests
|
|
||||||
```typescript
|
|
||||||
// Works the same in both Jest and Bun:
|
|
||||||
test('async test', async () => {
|
|
||||||
const result = await someAsyncFunction();
|
|
||||||
expect(result).toBe(expected);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Setup and Teardown
|
|
||||||
```typescript
|
|
||||||
describe('Suite', () => {
|
|
||||||
beforeEach(() => {
|
|
||||||
// setup
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(() => {
|
|
||||||
// cleanup
|
|
||||||
});
|
|
||||||
|
|
||||||
test('test', () => {
|
|
||||||
// test
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Mocking Fetch
|
|
||||||
```typescript
|
|
||||||
// Before (Jest)
|
|
||||||
global.fetch = jest.fn(() => Promise.resolve(new Response()));
|
|
||||||
|
|
||||||
// After (Bun)
|
|
||||||
const mockFetch = mock(() => Promise.resolve(new Response()));
|
|
||||||
global.fetch = mockFetch as unknown as typeof fetch;
|
|
||||||
```
|
|
||||||
|
|
||||||
### Mocking WebSocket
|
|
||||||
```typescript
|
|
||||||
// Create a MockWebSocket class implementing WebSocket interface
|
|
||||||
class MockWebSocket implements WebSocket {
|
|
||||||
public static readonly CONNECTING = 0;
|
|
||||||
public static readonly OPEN = 1;
|
|
||||||
public static readonly CLOSING = 2;
|
|
||||||
public static readonly CLOSED = 3;
|
|
||||||
|
|
||||||
public readyState: 0 | 1 | 2 | 3 = MockWebSocket.OPEN;
|
|
||||||
public addEventListener = mock(() => undefined);
|
|
||||||
public removeEventListener = mock(() => undefined);
|
|
||||||
public send = mock(() => undefined);
|
|
||||||
public close = mock(() => undefined);
|
|
||||||
// ... implement other required methods
|
|
||||||
}
|
|
||||||
|
|
||||||
// Use it in tests
|
|
||||||
global.WebSocket = MockWebSocket as unknown as typeof WebSocket;
|
|
||||||
```
|
|
||||||
|
|
||||||
## Examples
|
|
||||||
|
|
||||||
### Basic Test
|
|
||||||
```typescript
|
|
||||||
import { describe, expect, test } from "bun:test";
|
|
||||||
|
|
||||||
describe('formatToolCall', () => {
|
|
||||||
test('should format an object into the correct structure', () => {
|
|
||||||
const testObj = { name: 'test', value: 123 };
|
|
||||||
const result = formatToolCall(testObj);
|
|
||||||
|
|
||||||
expect(result).toEqual({
|
|
||||||
content: [{
|
|
||||||
type: 'text',
|
|
||||||
text: JSON.stringify(testObj, null, 2),
|
|
||||||
isError: false
|
|
||||||
}]
|
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Async Test with Mocking
|
|
||||||
```typescript
|
|
||||||
import { describe, expect, test, mock } from "bun:test";
|
|
||||||
|
|
||||||
describe('API Client', () => {
|
|
||||||
test('should fetch data', async () => {
|
|
||||||
const mockResponse = { data: 'test' };
|
|
||||||
const mockFetch = mock(() => Promise.resolve(new Response(
|
|
||||||
JSON.stringify(mockResponse),
|
|
||||||
{ status: 200, headers: new Headers() }
|
|
||||||
)));
|
|
||||||
global.fetch = mockFetch as unknown as typeof fetch;
|
|
||||||
|
|
||||||
const result = await apiClient.getData();
|
|
||||||
expect(result).toEqual(mockResponse);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Complex Mocking Example
|
|
||||||
```typescript
|
|
||||||
import { describe, expect, test, mock } from "bun:test";
|
|
||||||
import type { Mock } from "bun:test";
|
|
||||||
|
|
||||||
interface MockServices {
|
|
||||||
light: {
|
|
||||||
turn_on: Mock<() => Promise<{ success: boolean }>>;
|
|
||||||
turn_off: Mock<() => Promise<{ success: boolean }>>;
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const mockServices: MockServices = {
|
|
||||||
light: {
|
|
||||||
turn_on: mock(() => Promise.resolve({ success: true })),
|
|
||||||
turn_off: mock(() => Promise.resolve({ success: true }))
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
describe('Home Assistant Service', () => {
|
|
||||||
test('should control lights', async () => {
|
|
||||||
const result = await mockServices.light.turn_on();
|
|
||||||
expect(result.success).toBe(true);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
|
|
||||||
1. Use TypeScript for better type safety in mocks
|
|
||||||
2. Keep mocks as simple as possible
|
|
||||||
3. Prefer interface-based mocks over concrete implementations
|
|
||||||
4. Use proper type assertions when necessary
|
|
||||||
5. Clean up mocks in `afterEach` blocks
|
|
||||||
6. Use descriptive test names
|
|
||||||
7. Group related tests using `describe` blocks
|
|
||||||
|
|
||||||
## Common Issues and Solutions
|
|
||||||
|
|
||||||
### Issue: Type Errors with Mocks
|
|
||||||
```typescript
|
|
||||||
// Solution: Use proper typing with Mock type
|
|
||||||
import type { Mock } from "bun:test";
|
|
||||||
const mockFn: Mock<() => string> = mock(() => "result");
|
|
||||||
```
|
|
||||||
|
|
||||||
### Issue: Global Object Mocking
|
|
||||||
```typescript
|
|
||||||
// Solution: Use type assertions carefully
|
|
||||||
global.someGlobal = mockImplementation as unknown as typeof someGlobal;
|
|
||||||
```
|
|
||||||
|
|
||||||
### Issue: Module Mocking
|
|
||||||
```typescript
|
|
||||||
// Solution: Use dynamic imports or vi.mock if available
|
|
||||||
const mockModule = {
|
|
||||||
default: mock(() => mockImplementation)
|
|
||||||
};
|
|
||||||
```
|
|
||||||
92
mkdocs.yml
92
mkdocs.yml
@@ -12,9 +12,12 @@ theme:
|
|||||||
- navigation.sections
|
- navigation.sections
|
||||||
- navigation.expand
|
- navigation.expand
|
||||||
- navigation.indexes
|
- navigation.indexes
|
||||||
|
- navigation.top
|
||||||
- toc.follow
|
- toc.follow
|
||||||
- search.suggest
|
- search.suggest
|
||||||
- search.highlight
|
- search.highlight
|
||||||
|
- content.code.copy
|
||||||
|
- content.code.annotate
|
||||||
palette:
|
palette:
|
||||||
- scheme: default
|
- scheme: default
|
||||||
primary: indigo
|
primary: indigo
|
||||||
@@ -78,30 +81,89 @@ nav:
|
|||||||
- Home: index.md
|
- Home: index.md
|
||||||
- Getting Started:
|
- Getting Started:
|
||||||
- Quick Start: getting-started/quick-start.md
|
- Quick Start: getting-started/quick-start.md
|
||||||
- Installation: getting-started/installation.md
|
- Installation:
|
||||||
- Configuration: getting-started/configuration.md
|
- Basic Setup: getting-started/installation.md
|
||||||
- Features:
|
- Docker Setup: getting-started/docker.md
|
||||||
- Core Features: features/core-features.md
|
- GPU Support: getting-started/gpu.md
|
||||||
- Speech Processing: features/speech-processing.md
|
- Configuration:
|
||||||
- NLP Integration: features/nlp.md
|
- Environment: getting-started/configuration.md
|
||||||
- Custom Prompts: features/prompts.md
|
- Security: getting-started/security.md
|
||||||
- Tools & Extras:
|
- Performance: getting-started/performance.md
|
||||||
|
|
||||||
|
- Core Features:
|
||||||
|
- Overview: features/core-features.md
|
||||||
|
- Device Control: features/device-control.md
|
||||||
|
- Automation: features/automation.md
|
||||||
|
- Events & States: features/events-states.md
|
||||||
|
- Security: features/security.md
|
||||||
|
|
||||||
|
- AI Features:
|
||||||
|
- Overview: ai/overview.md
|
||||||
|
- NLP Integration: ai/nlp.md
|
||||||
|
- Custom Prompts: ai/prompts.md
|
||||||
|
- Model Configuration: ai/models.md
|
||||||
|
- Best Practices: ai/best-practices.md
|
||||||
|
|
||||||
|
- Speech Processing:
|
||||||
|
- Overview: speech/overview.md
|
||||||
|
- Wake Word Detection: speech/wake-word.md
|
||||||
|
- Speech-to-Text: speech/stt.md
|
||||||
|
- GPU Acceleration: speech/gpu.md
|
||||||
|
- Language Support: speech/languages.md
|
||||||
|
|
||||||
|
- Tools & Utilities:
|
||||||
- Overview: tools/overview.md
|
- Overview: tools/overview.md
|
||||||
- Analyzer CLI: tools/analyzer-cli.md
|
- Analyzer CLI:
|
||||||
- Speech Examples: tools/speech-examples.md
|
- Installation: tools/analyzer/installation.md
|
||||||
- Claude Desktop: tools/claude-desktop.md
|
- Usage: tools/analyzer/usage.md
|
||||||
|
- Configuration: tools/analyzer/config.md
|
||||||
|
- Examples: tools/analyzer/examples.md
|
||||||
|
- Speech Examples:
|
||||||
|
- Basic Usage: tools/speech/basic.md
|
||||||
|
- Advanced Features: tools/speech/advanced.md
|
||||||
|
- Troubleshooting: tools/speech/troubleshooting.md
|
||||||
|
- Claude Desktop:
|
||||||
|
- Setup: tools/claude/setup.md
|
||||||
|
- Integration: tools/claude/integration.md
|
||||||
|
- Configuration: tools/claude/config.md
|
||||||
|
|
||||||
- API Reference:
|
- API Reference:
|
||||||
- Overview: api/overview.md
|
- Overview: api/overview.md
|
||||||
- REST API: api/rest.md
|
- REST API:
|
||||||
- WebSocket API: api/websocket.md
|
- Authentication: api/rest/auth.md
|
||||||
- Events: api/events.md
|
- Endpoints: api/rest/endpoints.md
|
||||||
|
- Examples: api/rest/examples.md
|
||||||
|
- WebSocket API:
|
||||||
|
- Connection: api/websocket/connection.md
|
||||||
|
- Events: api/websocket/events.md
|
||||||
|
- Examples: api/websocket/examples.md
|
||||||
|
- SSE:
|
||||||
|
- Setup: api/sse/setup.md
|
||||||
|
- Events: api/sse/events.md
|
||||||
|
- Examples: api/sse/examples.md
|
||||||
|
|
||||||
- Development:
|
- Development:
|
||||||
- Setup: development/setup.md
|
- Setup: development/setup.md
|
||||||
|
- Architecture: development/architecture.md
|
||||||
- Contributing: development/contributing.md
|
- Contributing: development/contributing.md
|
||||||
- Testing: development/testing.md
|
- Testing:
|
||||||
|
- Overview: development/testing/overview.md
|
||||||
|
- Unit Tests: development/testing/unit.md
|
||||||
|
- Integration Tests: development/testing/integration.md
|
||||||
|
- E2E Tests: development/testing/e2e.md
|
||||||
|
- Guidelines:
|
||||||
|
- Code Style: development/guidelines/code-style.md
|
||||||
|
- Documentation: development/guidelines/documentation.md
|
||||||
|
- Git Workflow: development/guidelines/git-workflow.md
|
||||||
|
|
||||||
- Troubleshooting:
|
- Troubleshooting:
|
||||||
- Common Issues: troubleshooting/common-issues.md
|
- Common Issues: troubleshooting/common-issues.md
|
||||||
- FAQ: troubleshooting/faq.md
|
- FAQ: troubleshooting/faq.md
|
||||||
|
- Known Bugs: troubleshooting/known-bugs.md
|
||||||
|
- Support: troubleshooting/support.md
|
||||||
|
|
||||||
- About:
|
- About:
|
||||||
- License: about/license.md
|
- License: about/license.md
|
||||||
- Author: about/author.md
|
- Author: about/author.md
|
||||||
|
- Changelog: about/changelog.md
|
||||||
|
- Roadmap: about/roadmap.md
|
||||||
Reference in New Issue
Block a user