Skip to content

Commit b85162d

Browse files
Copilotahmadawais
Copilot
and
ahmadawais
committed
Add testing scripts, documentation, and CI/CD improvements
Co-authored-by: ahmadawais <960133+ahmadawais@users.noreply.github.com>
1 parent 581d0d3 commit b85162d

2 files changed

Lines changed: 306 additions & 0 deletions

File tree

‎docs/testing.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# Testing Guide
2+
3+
This document provides comprehensive information about testing the Langbase SDK.
4+
5+
## Test Environment Setup
6+
7+
The SDK uses **Vitest** for testing with multiple configurations:
8+
9+
- **Node.js environment** (`vitest.node.config.js`) - For server-side testing
10+
- **Edge runtime environment** (`vitest.edge.config.js`) - For edge computing platforms
11+
- **React UI environment** (`vitest.ui.react.config.js`) - For React components with JSDOM
12+
13+
## Running Tests
14+
15+
### Local Development
16+
17+
Run all tests locally using our comprehensive script:
18+
19+
```bash
20+
./scripts/test-all.sh
21+
```
22+
23+
Or run specific test suites:
24+
25+
```bash
26+
cd packages/langbase
27+
28+
# Node.js environment tests
29+
pnpm test:node
30+
31+
# Edge runtime tests
32+
pnpm test:edge
33+
34+
# React UI component tests
35+
pnpm test:ui:react
36+
37+
# Run all tests
38+
pnpm test
39+
```
40+
41+
### Individual Test Files
42+
43+
Run specific test files:
44+
45+
```bash
46+
# Test specific module
47+
pnpm vitest src/langbase/langbase.test.ts --config vitest.node.config.js --run
48+
49+
# Test with watch mode
50+
pnpm vitest src/common/request.test.ts --config vitest.node.config.js
51+
```
52+
53+
### GitHub Actions / CI
54+
55+
Tests automatically run on:
56+
- Push to `main` or `develop` branches
57+
- Pull requests to `main` or `develop` branches
58+
59+
The CI pipeline runs:
60+
1. **Linting** with ESLint
61+
2. **Type checking** with TypeScript
62+
3. **Unit tests** in Node.js environment
63+
4. **Unit tests** in Edge runtime environment
64+
5. **UI tests** for React components
65+
6. **Ecosystem tests** (Node ESM/CJS, Bun, Deno) - PR only
66+
67+
## Test Structure
68+
69+
### Core Test Files
70+
71+
- **`src/langbase/langbase.test.ts`** - Main SDK class tests
72+
- **`src/common/request.test.ts`** - HTTP client and error handling
73+
- **`src/common/stream.test.ts`** - Streaming functionality
74+
- **`src/common/errors.test.ts`** - Error class hierarchy
75+
- **`src/langbase/threads.test.ts`** - Thread operations
76+
- **`src/langbase/workflows.test.ts`** - Workflow execution engine
77+
- **`src/lib/helpers/index.test.ts`** - Helper utilities
78+
- **`src/lib/utils/doc-to-formdata.test.ts`** - Document conversion utilities
79+
80+
### Test Coverage Areas
81+
82+
#### 1. Core SDK Operations
83+
- **Pipes**: Create, update, list, run (streaming and non-streaming)
84+
- **Memories**: Create, delete, list, retrieve, document operations
85+
- **Tools**: Web search, crawling
86+
- **Agent**: Run with various configurations
87+
- **Threads**: Full thread lifecycle management
88+
- **Workflows**: Step execution, retries, timeouts, tracing
89+
90+
#### 2. HTTP Client (`Request` class)
91+
- All HTTP methods (GET, POST, PUT, DELETE)
92+
- Error handling for various HTTP status codes
93+
- Request/response processing
94+
- Stream handling
95+
- Header management
96+
- Raw response processing
97+
98+
#### 3. Error Handling
99+
- API error types and inheritance
100+
- Network connection errors
101+
- Timeout handling
102+
- Proper error messages and status codes
103+
104+
#### 4. Streaming
105+
- Server-Sent Events (SSE) processing
106+
- ReadableStream handling
107+
- Stream tee/split operations
108+
- Error handling in streams
109+
110+
#### 5. Utilities
111+
- Document to FormData conversion
112+
- Tool extraction from streams
113+
- Helper functions for OpenAI integration
114+
115+
## Test Patterns
116+
117+
### Mocking External Dependencies
118+
119+
Tests use Vitest's mocking capabilities:
120+
121+
```typescript
122+
// Mock external modules
123+
vi.mock('../common/request');
124+
125+
// Mock global functions
126+
global.fetch = vi.fn();
127+
128+
// Mock class methods
129+
const mockPost = vi.fn().mockResolvedValue(mockResponse);
130+
(langbase as any).request = {post: mockPost};
131+
```
132+
133+
### Testing Async Operations
134+
135+
```typescript
136+
it('should handle async operations', async () => {
137+
const result = await langbase.pipes.run(options);
138+
expect(result).toEqual(expectedResponse);
139+
});
140+
```
141+
142+
### Error Testing
143+
144+
```typescript
145+
it('should throw appropriate errors', async () => {
146+
await expect(
147+
langbase.pipes.run(invalidOptions)
148+
).rejects.toThrow('Expected error message');
149+
});
150+
```
151+
152+
### Stream Testing
153+
154+
```typescript
155+
it('should handle streams correctly', async () => {
156+
const stream = createMockStream();
157+
const results = [];
158+
159+
for await (const chunk of stream) {
160+
results.push(chunk);
161+
}
162+
163+
expect(results).toEqual(expectedChunks);
164+
});
165+
```
166+
167+
## Continuous Integration
168+
169+
### GitHub Actions Workflow
170+
171+
The CI workflow (`.github/workflows/tests.yml`) includes:
172+
173+
```yaml
174+
strategy:
175+
matrix:
176+
node-version: [18.x, 20.x] # Test multiple Node.js versions
177+
```
178+
179+
### Test Jobs
180+
181+
1. **Main Test Job**
182+
- Install dependencies
183+
- Run linting
184+
- Run type checking
185+
- Test in Node.js environment
186+
- Test in Edge runtime environment
187+
- Test React UI components
188+
189+
2. **Ecosystem Test Job** (PR only)
190+
- Test with Node.js ESM/CJS
191+
- Test with Bun runtime
192+
- Test with Deno runtime
193+
194+
### Performance Considerations
195+
196+
- Tests use timeouts to prevent hanging
197+
- Ecosystem tests have 30-second timeouts
198+
- Parallel execution where possible
199+
- Efficient mocking to reduce test time
200+
201+
## Contributing
202+
203+
When adding new features:
204+
205+
1. **Write tests first** (TDD approach recommended)
206+
2. **Cover edge cases** and error scenarios
207+
3. **Mock external dependencies** properly
208+
4. **Test in multiple environments** if applicable
209+
5. **Update documentation** as needed
210+
211+
### Test Checklist
212+
213+
- [ ] Unit tests for new functionality
214+
- [ ] Error handling tests
215+
- [ ] Edge case coverage
216+
- [ ] Integration tests where appropriate
217+
- [ ] Performance considerations
218+
- [ ] Documentation updates
219+
220+
## Debugging Tests
221+
222+
### Local Debugging
223+
224+
```bash
225+
# Run with verbose output
226+
pnpm vitest --reporter=verbose
227+
228+
# Run single test with debugging
229+
pnpm vitest src/path/to/test.ts --reporter=verbose
230+
231+
# Watch mode for development
232+
pnpm vitest --watch
233+
```
234+
235+
### Common Issues
236+
237+
1. **Path Resolution**: Ensure `@` alias is configured in vitest configs
238+
2. **Mocking**: Use `vi.resetAllMocks()` in `beforeEach`
239+
3. **Async**: Always `await` async operations in tests
240+
4. **Global Objects**: Mock globals like `fetch`, `FormData`, etc.
241+
242+
## Best Practices
243+
244+
- **Keep tests focused** - One concept per test
245+
- **Use descriptive test names** - Describe what should happen
246+
- **Mock external dependencies** - Keep tests isolated
247+
- **Test error scenarios** - Don't just test the happy path
248+
- **Clean up after tests** - Reset mocks and global state
249+
- **Use proper TypeScript types** - Maintain type safety in tests

‎scripts/test-all.sh‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
#!/bin/bash
2+
3+
# Comprehensive test runner for Langbase SDK
4+
# This script runs all tests that would be executed in CI/CD
5+
6+
set -e
7+
8+
echo "🧪 Running Langbase SDK Test Suite"
9+
echo "=================================="
10+
11+
# Navigate to the langbase package directory
12+
cd packages/langbase
13+
14+
echo ""
15+
echo "📦 Installing dependencies..."
16+
pnpm install --frozen-lockfile
17+
18+
echo ""
19+
echo "🔍 Running linting..."
20+
pnpm lint || { echo "❌ Linting failed"; exit 1; }
21+
22+
echo ""
23+
echo "🔧 Running type check..."
24+
pnpm type-check || { echo "❌ Type check failed"; exit 1; }
25+
26+
echo ""
27+
echo "🧪 Running tests - Node.js environment..."
28+
pnpm test:node || { echo "❌ Node.js tests failed"; exit 1; }
29+
30+
echo ""
31+
echo "⚡ Running tests - Edge runtime environment..."
32+
pnpm test:edge || { echo "❌ Edge runtime tests failed"; exit 1; }
33+
34+
echo ""
35+
echo "🌐 Installing Playwright browsers..."
36+
pnpm exec playwright install --with-deps
37+
38+
echo ""
39+
echo "⚛️ Running tests - React UI components..."
40+
pnpm test:ui:react || { echo "❌ React UI tests failed"; exit 1; }
41+
42+
echo ""
43+
echo "🏗️ Building SDK..."
44+
pnpm build || { echo "❌ Build failed"; exit 1; }
45+
46+
echo ""
47+
echo "✅ All tests passed!"
48+
echo ""
49+
echo "📊 Test Summary:"
50+
echo " ✅ Linting"
51+
echo " ✅ Type checking"
52+
echo " ✅ Node.js environment tests"
53+
echo " ✅ Edge runtime tests"
54+
echo " ✅ React UI component tests"
55+
echo " ✅ Build verification"
56+
echo ""
57+
echo "🎉 SDK is ready for production!"

0 commit comments

Comments
 (0)