feat: add SnapshotAgent for HTTP request recording and playback

docs/docsify/sidebar.md

@@ -19,6 +19,7 @@
   * [MockClient](/docs/api/MockClient.md "Undici API - MockClient")
   * [MockPool](/docs/api/MockPool.md "Undici API - MockPool")
   * [MockAgent](/docs/api/MockAgent.md "Undici API - MockAgent")
+  * [SnapshotAgent](/docs/api/SnapshotAgent.md "Undici API - SnapshotAgent")
   * [MockCallHistory](/docs/api/MockCallHistory.md "Undici API - MockCallHistory")
   * [MockCallHistoryLog](/docs/api/MockCallHistoryLog.md "Undici API - MockCallHistoryLog")
   * [MockErrors](/docs/api/MockErrors.md "Undici API - MockErrors")

docs/examples/snapshot-testing.js

@@ -0,0 +1,109 @@
+const { SnapshotAgent, setGlobalDispatcher, getGlobalDispatcher, request } = require('../../index.js')
+const { createServer } = require('node:http')
+const { promisify } = require('node:util')
+const { tmpdir } = require('node:os')
+const { join } = require('node:path')
+
+/**
+ * Example: Basic Snapshot Testing
+ *
+ * This example demonstrates how to use SnapshotAgent to record API
+ * interactions and replay them in tests for consistent, offline testing.
+ */
+
+async function basicSnapshotExample () {
+  console.log('🚀 Basic Snapshot Testing Example\n')
+
+  // Create a temporary snapshot file path
+  const snapshotPath = join(tmpdir(), `snapshot-example-${Date.now()}.json`)
+  console.log(`📁 Using temporary snapshot file: ${snapshotPath}\n`)
+
+  // Create a local test server
+  const server = createServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({
+      message: 'Hello from test server!',
+      timestamp: new Date().toISOString(),
+      path: req.url
+    }))
+  })
+
+  await promisify(server.listen.bind(server))(0)
+  const { port } = server.address()
+  const origin = `http://localhost:${port}`
+
+  try {
+    // Step 1: Record mode - capture API responses
+    console.log('📹 Step 1: Recording API response...')
+
+    const recordingAgent = new SnapshotAgent({
+      mode: 'record',
+      snapshotPath
+    })
+
+    const originalDispatcher = getGlobalDispatcher()
+    setGlobalDispatcher(recordingAgent)
+
+    try {
+      // Make an API call that will be recorded
+      const response = await request(`${origin}/api/test`)
+      const data = await response.body.json()
+
+      console.log(`✅ Recorded response: ${data.message}`)
+
+      // Save the recorded snapshots
+      await recordingAgent.saveSnapshots()
+      console.log('💾 Snapshot saved to temporary file\n')
+    } finally {
+      setGlobalDispatcher(originalDispatcher)
+      recordingAgent.close()
+    }
+
+    // Step 2: Playback mode - use recorded responses (server can be down)
+    console.log('🎬 Step 2: Playing back recorded response...')
+    server.close() // Close server to prove we're using snapshots
+
+    const playbackAgent = new SnapshotAgent({
+      mode: 'playback',
+      snapshotPath
+    })
+
+    setGlobalDispatcher(playbackAgent)
+
+    try {
+      // This will use the recorded response instead of making a real request
+      const response = await request(`${origin}/api/test`)
+      const data = await response.body.json()
+
+      console.log(`✅ Playback response: ${data.message}`)
+      console.log('🎉 Successfully used recorded data instead of live server!')
+    } finally {
+      setGlobalDispatcher(originalDispatcher)
+      playbackAgent.close()
+    }
+  } finally {
+    // Ensure server is closed
+    if (server.listening) {
+      server.close()
+    }
+
+    // Clean up temporary file
+    try {
+      const { unlink } = require('node:fs/promises')
+      await unlink(snapshotPath)
+      console.log('\n🗑️  Cleaned up temporary snapshot file')
+    } catch (error) {
+      // File might not exist or already be deleted
+    }
+  }
+}
+
+// Main execution
+async function main () {
+  await basicSnapshotExample()
+}
+
+// Run if called directly
+if (require.main === module) {
+  main().catch(console.error)
+}

index.js

@@ -18,6 +18,7 @@ const MockClient = require('./lib/mock/mock-client')
 const { MockCallHistory, MockCallHistoryLog } = require('./lib/mock/mock-call-history')
 const MockAgent = require('./lib/mock/mock-agent')
 const MockPool = require('./lib/mock/mock-pool')
+const SnapshotAgent = require('./lib/mock/snapshot-agent')
 const mockErrors = require('./lib/mock/mock-errors')
 const RetryHandler = require('./lib/handler/retry-handler')
 const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
@@ -178,6 +179,7 @@ module.exports.MockCallHistory = MockCallHistory
 module.exports.MockCallHistoryLog = MockCallHistoryLog
 module.exports.MockPool = MockPool
 module.exports.MockAgent = MockAgent
+module.exports.SnapshotAgent = SnapshotAgent
 module.exports.mockErrors = mockErrors
 
 const { EventSource } = require('./lib/web/eventsource/eventsource')