alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Restructure MkDocs navigation and remove test migration guide

Browse Source 
- 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
2025-02-06 10:36:50 +01:00
parent 61e930bf8a
commit 9d125a87d9
2 changed files with 78 additions and 339 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
docs/development/test-migration-guide.md
View File

@@ -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
View File

@@ -12,9 +12,12 @@ theme:
- navigation.sections
- navigation.expand
- navigation.indexes
- navigation.top
- toc.follow
- search.suggest
- search.highlight
- content.code.copy
- content.code.annotate
palette:
- scheme: default
primary: indigo
@@ -78,30 +81,89 @@ nav:
- Home: index.md
- Getting Started:
- Quick Start: getting-started/quick-start.md
- Installation: getting-started/installation.md
- Configuration: getting-started/configuration.md
- Features:
- Core Features: features/core-features.md
- Speech Processing: features/speech-processing.md
- NLP Integration: features/nlp.md
- Custom Prompts: features/prompts.md
- Tools & Extras:
- Installation:
- Basic Setup: getting-started/installation.md
- Docker Setup: getting-started/docker.md
- GPU Support: getting-started/gpu.md
- Configuration:
- Environment: getting-started/configuration.md
- Security: getting-started/security.md
- 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
- Analyzer CLI: tools/analyzer-cli.md
- Speech Examples: tools/speech-examples.md
- Claude Desktop: tools/claude-desktop.md
- Analyzer CLI:
- Installation: tools/analyzer/installation.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:
- Overview: api/overview.md
- REST API: api/rest.md
- WebSocket API: api/websocket.md
- Events: api/events.md
- REST API:
- Authentication: api/rest/auth.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:
- Setup: development/setup.md
- Architecture: development/architecture.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:
- Common Issues: troubleshooting/common-issues.md
- FAQ: troubleshooting/faq.md
- Known Bugs: troubleshooting/known-bugs.md
- Support: troubleshooting/support.md
- About:
- License: about/license.md
- Author: about/author.md
- Changelog: about/changelog.md
- Roadmap: about/roadmap.md