rird 2.1.231 → 2.3.0

package/TESTING.md

@@ -0,0 +1,512 @@
+# RIRD CLI Testing Guide
+
+Complete guide for running, writing, and maintaining tests for the RIRD CLI.
+
+## Quick Start
+
+### Run All Tests
+```bash
+npm test
+# or
+bun test
+```
+
+### Run Tests in Watch Mode
+```bash
+npm run test:watch
+```
+
+### Run Specific Test File
+```bash
+bun test test/util/license.test.ts
+```
+
+## Test Organization
+
+```
+test/
+├── agent/                 # Agent functionality
+├── cli/
+│   └── cmd/              # Command tests
+│       ├── acp.test.ts   # ACP server tests
+│       └── run.test.ts   # Run command tests
+├── config/               # Configuration tests
+├── installation/
+│   └── installation.test.ts  # Installation & upgrade
+├── provider/             # Provider discovery tests
+├── util/
+│   └── license.test.ts   # License validation
+├── helpers.ts            # Shared test utilities
+└── fixture/
+    └── fixture.ts        # Test fixtures
+```
+
+## Writing Tests
+
+### Basic Test Structure
+
+```typescript
+import { test, expect, describe } from "bun:test"
+
+describe("Feature Name", () => {
+  test("should do something", () => {
+    expect(2 + 2).toBe(4)
+  })
+
+  test("should handle error cases", () => {
+    expect(() => {
+      throw new Error("oops")
+    }).toThrow()
+  })
+})
+```
+
+### Async Tests
+
+```typescript
+test("should load async data", async () => {
+  const result = await someAsyncFunction()
+  expect(result).toBeDefined()
+})
+```
+
+### Using Mock Helpers
+
+```typescript
+import { createMockLicense, mockEnv, mockHttpServer } from "../helpers"
+
+test("should validate license", async () => {
+  const mockLicense = createMockLicense("test-key", "user@example.com", "pro")
+
+  const restoreEnv = mockEnv({ RIRD_LICENSE_KEY: mockLicense.key })
+
+  try {
+    // Your test code
+  } finally {
+    restoreEnv()
+  }
+})
+```
+
+### Using Temporary Files
+
+```typescript
+import { createTmpFile, cleanupTmpFile } from "../helpers"
+
+test("should write and read files", async () => {
+  const filePath = await createTmpFile("test content", "myfile")
+
+  try {
+    const content = await Bun.file(filePath).text()
+    expect(content).toBe("test content")
+  } finally {
+    await cleanupTmpFile(filePath)
+  }
+})
+```
+
+### Using Test Fixtures
+
+```typescript
+import { tmpdir } from "../fixture/fixture"
+import { Instance } from "../../src/project/instance"
+
+test("should work with project instance", async () => {
+  await using tmp = await tmpdir({
+    init: async (dir) => {
+      // Setup files in temp directory
+      await Bun.write(`${dir}/config.json`, JSON.stringify({}))
+    }
+  })
+
+  await Instance.provide({
+    directory: tmp.path,
+    fn: async () => {
+      // Run code in temporary project context
+    }
+  })
+})
+```
+
+## Available Test Helpers
+
+### Mock Factories
+
+#### `createMockProvider(name?, apiKey?, enabled?)`
+Creates a mock LLM provider object.
+
+```typescript
+const provider = createMockProvider("anthropic", "sk-test-key", true)
+```
+
+#### `createMockLicense(key?, email?, plan?)`
+Creates a mock license object.
+
+```typescript
+const license = createMockLicense("lic-123", "admin@example.com", "enterprise")
+```
+
+### HTTP Server Mocking
+
+#### `mockHttpServer(responses?)`
+Creates a test HTTP server.
+
+```typescript
+const { server, port, close } = await mockHttpServer({
+  "/api/validate": { valid: true },
+  "/api/status": (req) => new Response(JSON.stringify({ status: "ok" }))
+})
+
+try {
+  const result = await fetch(`http://127.0.0.1:${port}/api/validate`)
+} finally {
+  close()
+}
+```
+
+### Environment Variables
+
+#### `mockEnv(vars)`
+Temporarily sets environment variables.
+
+```typescript
+const restore = mockEnv({
+  RIRD_LICENSE_KEY: "test-key",
+  DEBUG: "true"
+})
+
+// Environment is mocked
+expect(process.env.RIRD_LICENSE_KEY).toBe("test-key")
+
+restore() // Environment is restored
+```
+
+### File System Utilities
+
+#### `createTmpFile(content, name?)`
+Creates a temporary file.
+
+```typescript
+const path = await createTmpFile("file content", "testfile")
+```
+
+#### `cleanupTmpFile(filePath)`
+Removes a temporary file.
+
+```typescript
+await cleanupTmpFile(path)
+```
+
+### Test Configuration
+
+#### `createTestConfig()`
+Creates temporary test configuration.
+
+```typescript
+const { configDir, configFile } = await createTestConfig()
+```
+
+#### `waitFor(fn, timeout?, interval?)`
+Waits for async condition with timeout.
+
+```typescript
+await waitFor(() => fileExists(path), 5000, 100)
+```
+
+## Test Coverage Requirements
+
+### Critical Modules (Must Have Tests)
+
+1. **License Validation** (util/license.ts)
+   - License key loading
+   - License validation
+   - Cache management
+   - Error handling
+
+2. **CLI Commands** (cli/cmd/*.ts)
+   - Command definition
+   - Argument parsing
+   - Option handling
+   - Handler functions
+
+3. **Installation** (installation/index.ts)
+   - Version detection
+   - Installation method detection
+   - Upgrade functionality
+   - Error handling
+
+4. **Provider System** (provider/provider.ts)
+   - Provider discovery
+   - Configuration loading
+   - Multi-provider support
+   - Environment variable handling
+
+### Test Categories
+
+#### Unit Tests
+- Pure function testing
+- Input/output verification
+- Error cases
+
+#### Integration Tests
+- Component interaction
+- Configuration loading
+- File system operations
+
+#### Async Tests
+- Promise handling
+- Error propagation
+- Timeout behavior
+
+## Best Practices
+
+### Test Naming
+Use clear, descriptive names that explain what is being tested:
+
+```typescript
+// Good
+test("should fail when license key is missing", async () => {})
+test("should save license key to file with correct permissions", async () => {})
+
+// Bad
+test("license test", async () => {})
+test("fails", async () => {})
+```
+
+### Assertions
+Be specific with assertions:
+
+```typescript
+// Good
+expect(result.valid).toBe(false)
+expect(result.message).toContain("No license key found")
+
+// Bad
+expect(result).toBeDefined()
+```
+
+### Cleanup
+Always clean up resources:
+
+```typescript
+test("should manage resources", async () => {
+  const file = await createTmpFile("content", "test")
+
+  try {
+    // Test code
+  } finally {
+    await cleanupTmpFile(file) // Always cleanup
+  }
+})
+```
+
+### Test Isolation
+Keep tests independent:
+
+```typescript
+describe("Feature", () => {
+  let cleanup: () => void
+
+  beforeEach(() => {
+    cleanup = mockEnv({ TEST_VAR: "value" })
+  })
+
+  afterEach(() => {
+    cleanup() // Restore state
+  })
+
+  test("uses TEST_VAR", () => {
+    expect(process.env.TEST_VAR).toBe("value")
+  })
+})
+```
+
+### Error Testing
+Test both success and failure paths:
+
+```typescript
+test("should validate license", async () => {
+  // Success case
+  const validResult = await validateLicense("valid-key")
+  expect(validResult.valid).toBe(true)
+
+  // Failure case
+  const invalidResult = await validateLicense("invalid-key")
+  expect(invalidResult.valid).toBe(false)
+})
+```
+
+## Running Tests in CI
+
+### GitHub Actions Example
+
+```yaml
+name: Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: oven-sh/setup-bun@v1
+      - run: bun install
+      - run: bun test
+```
+
+### CI Best Practices
+
+1. Run tests on every push
+2. Fail CI if tests fail
+3. Cache dependencies
+4. Set timeouts for long-running tests
+5. Report test results
+
+## Debugging Tests
+
+### Verbose Output
+```bash
+bun test --verbose
+```
+
+### Run Single Test
+```bash
+bun test --grep "License validation"
+```
+
+### Watch Specific File
+```bash
+bun test test/util/license.test.ts --watch
+```
+
+### Debug with Console
+```typescript
+test("debug test", () => {
+  console.log("Debug output:", someValue)
+  expect(someValue).toBeDefined()
+})
+```
+
+## Common Testing Patterns
+
+### Testing Async Functions
+
+```typescript
+test("should handle async operations", async () => {
+  const result = await asyncFunction()
+  expect(result).toEqual(expectedValue)
+})
+```
+
+### Testing Error Throwing
+
+```typescript
+test("should throw on invalid input", () => {
+  expect(() => {
+    functionThatThrows("bad")
+  }).toThrow("expected error message")
+})
+```
+
+### Testing with Timeouts
+
+```typescript
+test("should timeout appropriately", async () => {
+  const promise = longRunningOperation()
+
+  await expect(
+    Promise.race([promise, timeout(1000)])
+  ).rejects.toThrow("Timeout")
+})
+```
+
+### Testing with Mocked HTTP
+
+```typescript
+test("should call API", async () => {
+  const { server, port, close } = await mockHttpServer({
+    "/api/data": { id: 1, name: "test" }
+  })
+
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/data`)
+    const data = await response.json()
+    expect(data.name).toBe("test")
+  } finally {
+    close()
+  }
+})
+```
+
+## Troubleshooting
+
+### Tests Hanging
+- Check for unresolved promises
+- Verify async/await usage
+- Set timeout: `bun test --timeout 30000`
+
+### Module Not Found
+- Verify import paths
+- Check file existence
+- Ensure tsconfig includes test files
+
+### Permission Errors
+- Check temp directory permissions
+- Verify .rird directory is writable
+- Run with appropriate privileges
+
+### Network Tests Failing
+- Expected in offline environments
+- Mock HTTP calls in tests
+- Use mockHttpServer helper
+
+## Performance
+
+### Test Execution Time
+
+Current test suite executes in:
+- Unit tests: < 1 second
+- Integration tests: 1-5 seconds
+- Full suite: < 10 seconds
+
+Optimize slow tests by:
+- Mocking external calls
+- Using tmpdir fixtures
+- Avoiding unnecessary waits
+
+## Maintenance
+
+### When to Add Tests
+
+1. When fixing bugs - add regression test
+2. When adding features - add feature test
+3. When refactoring - maintain existing tests
+4. When improving error handling - add error test
+
+### When to Update Tests
+
+1. When changing function signatures
+2. When modifying error messages
+3. When updating file formats
+4. When changing environment variables
+
+### Deprecating Tests
+
+1. Mark test with skip or only
+2. Document why it's deprecated
+3. Create replacement test
+4. Remove after replacement verified
+
+## Test Statistics
+
+- **Total Test Files**: 32
+- **Total Test Cases**: 100+
+- **Critical Modules**: 5
+- **Helper Utilities**: 10+
+- **Code Coverage**: Core paths covered
+
+## Resources
+
+- [Bun Test Documentation](https://bun.sh/docs/test/basics)
+- [Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
+- [RIRD CLI Documentation](./CLAUDE.md)