Deepgram Local Dev Loop
Overview
Set up a fast local development workflow for Deepgram: test fixtures with sample audio, mock responses for offline unit tests, Vitest integration tests against the real API, and a watch-mode transcription dev server.
Prerequisites
@deepgram/sdk installed, DEEPGRAM_API_KEY configurednpm install -D vitest tsx dotenv for testing and dev server- Optional:
curl for downloading test fixtures
Instructions
Step 1: Project Structure
mkdir -p src tests/mocks fixtures
touch src/transcribe.ts tests/transcribe.test.ts tests/mocks/deepgram-responses.ts
Step 2: Download Test Fixtures
curl -o fixtures/nasa-podcast.wav \
https://static.deepgram.com/examples/nasa-podcast.wav
curl -o fixtures/bueller.wav \
https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav
Step 3: Environment Config
DEEPGRAM_API_KEY=your-dev-key
DEEPGRAM_MODEL=nova-3
DEEPGRAM_API_KEY=your-test-key
DEEPGRAM_MODEL=base
{
"scripts": {
"dev": "tsx watch src/transcribe.ts",
"test": "vitest",
"test:watch": "vitest --watch",
"test:integration": "vitest run tests/integration/"
}
}
Step 4: Mock Deepgram Responses
export const mockPrerecordedResult = {
metadata: {
request_id: 'mock-request-id-001',
created: '2026-01-01T00:00:00.000Z',
duration: 12.5,
channels: 1,
models: ['nova-3'],
model_info: { 'nova-3': { name: 'nova-3', version: '2026-01-01' } },
},
results: {
channels: [{
alternatives: [{
transcript: 'Life moves pretty fast. If you don\'t stop and look around once in a while, you could miss it.',
confidence: 0.98,
words: [
{ word: 'life', start: 0.08, end: 0.32, confidence: 0.99, punctuated_word: 'Life' },
{ word: 'moves', start: 0.32, end: 0.56, confidence: 0.98, punctuated_word: 'moves' },
{ word: 'pretty', start: 0.56, end: , : , : },
{ : , : , : , : , : },
],
}],
}],
: [{
: ,
: ,
: ,
: ,
: ,
}],
},
};
mockLiveTranscript = {
: ,
: [, ],
: ,
: ,
: ,
: ,
: {
: [{
: ,
: ,
: [
{ : , : , : , : , : },
{ : , : , : , : , : },
],
}],
},
};
mockTtsResponse = {
: ,
: ,
: ,
: { : , : },
};
Step 5: Unit Tests with Mocks
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { mockPrerecordedResult } from './mocks/deepgram-responses';
vi.mock('@deepgram/sdk', () => ({
createClient: () => ({
listen: {
prerecorded: {
transcribeUrl: vi.fn().mockResolvedValue({
result: mockPrerecordedResult,
error: null,
}),
transcribeFile: vi.fn().mockResolvedValue({
result: mockPrerecordedResult,
error: null,
}),
},
},
speak: {
request: vi.fn().mockResolvedValue({
getStream: () => Promise.resolve(null),
}),
},
}),
}));
describe('DeepgramTranscriber', () => {
it('transcribes URL and returns transcript text', async () => {
const { createClient } = await import('@deepgram/sdk');
const client = ();
{ result } = client...(
{ : },
{ : , : }
);
(result..[].[].).();
(result..).();
(result..).();
});
(, () => {
{ createClient } = ();
client = ();
{ result } = client...(
{ : },
{ : }
);
words = result..[].[].;
(words[].).();
(words[].).();
(words[].).();
});
});
Step 6: Integration Tests (Real API)
import { describe, it, expect } from 'vitest';
import { createClient } from '@deepgram/sdk';
describe('Deepgram Integration', () => {
const client = createClient(process.env.DEEPGRAM_API_KEY!);
it('transcribes sample audio URL', async () => {
const { result, error } = await client.listen.prerecorded.transcribeUrl(
{ url: 'https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav' },
{ model: 'nova-3', smart_format: true }
);
expect(error).toBeNull();
expect(result.results.channels[0].alternatives[0].transcript).toBeTruthy();
expect(result.results.channels[0].alternatives[0].confidence).toBeGreaterThan(0.8);
}, 30000);
it(, () => {
{ result, error } = client..();
(error).();
(result..).();
});
});
Output
- Project structure with src, tests, fixtures directories
- Mock response objects matching real Deepgram API shape
- Unit tests with mocked SDK (no API calls)
- Integration tests against real API with timeout
- Watch mode for rapid iteration
Error Handling
| Error | Cause | Solution |
|---|
| Fixture 404 | Deepgram moved sample URL | Check latest URLs at developers.deepgram.com |
DEEPGRAM_API_KEY undefined in test | .env.test not loaded | Configure Vitest env or use dotenv/config |
| Integration test timeout | Network or API slow | Increase timeout to 30000ms |
| Mock shape mismatch | API response changed | Update mocks from real response capture |
Resources
Next Steps
Proceed to deepgram-sdk-patterns for production-ready code patterns.
