HTTP Request Recording and Playback Proxy

5.0.1 · active · verified Wed Apr 22

Yakbak is a Node.js library for recording and playing back HTTP interactions, serving as a "VCR" for your HTTP clients during testing and development. It operates as a reverse proxy: requests are forwarded to a target host, and their responses are recorded ("taped") to disk. Subsequent identical requests are then played back from these recorded tapes instead of hitting the remote server, enabling consistent and fast test runs. Tapes are stored as `.js` files (Node modules), allowing for standalone replay servers. The current stable version is 5.0.1. While there isn't a strict release cadence, updates appear to be driven by dependency maintenance and Node.js version compatibility. Key differentiators include its reverse proxy approach, the flexible storage of tapes as re-executable Node modules, and its seamless integration with Node's native `http` module or popular frameworks like Express.

Common errors

```
Error: file is required
Usage: yakbak <file>
```
cause The `yakbak` command-line utility was executed without specifying the path to a recorded tape file as an argument.

fix Provide the path to a recorded tape file that you wish to serve, for example: `yakbak ./tapes/your-tape-id.js`.

Warnings

breaking Yakbak v5.0.0 dropped support for Node.js versions older than 10. Users on unsupported Node.js runtimes will encounter errors or unexpected behavior.
Fix: Upgrade your Node.js environment to version 10 or higher to ensure compatibility.
gotcha The `dirname` option is mandatory when initializing `yakbak(host, options)`. Failure to provide a valid path will result in errors during operation when the library attempts to save or load recorded tapes.
Fix: Always specify a valid, writable directory path for `dirname` in the options object, e.g., `{ dirname: path.join(__dirname, 'tapes') }`.
gotcha When the `noRecord` option is set to `true`, Yakbak will return a 404 Not Found error for any request where a matching tape does not already exist on disk. It will *not* proxy the request to the target host and record it.
Fix: Be aware of the `noRecord` option's behavior. If you want requests to be recorded when no tape exists, ensure `noRecord` is `false` or omitted (as it defaults to `false`).

Install

npm install yakbak npm
yarn add yakbak yarn
pnpm add yakbak pnpm

Imports

yakbak
wrong:
```
const yakbak = require('yakbak').yakbak;
```
correct:
```
import yakbak from 'yakbak';
```
Yakbak exports a function directly (default export in CJS/ESM), which takes the target host and options, and returns an `http.Server` request handler function.
yakbak (CommonJS)
wrong:
```
import yakbak from 'yakbak';
```
correct:
```
const yakbak = require('yakbak');
```
This is the traditional CommonJS import pattern commonly used in older Node.js projects or for direct `require` usage.
Tape handler
```
const tape = require('./tapes/1117f3d81490d441d826dd2fb26470f9.js');
```
Individual recorded tapes are saved as Node.js modules (CommonJS) and can be required directly to create a server that replays a single, specific recorded response.

Quickstart

This quickstart demonstrates setting up a Yakbak proxy server using Node's `http` module. It configures Yakbak to record or playback requests to `https://httpbin.org` and then makes a client request through the proxy to show the interaction, cleaning up the generated tapes afterwards.

const http = require('http');
const path = require('path');
const fs = require('fs');
const yakbak = require('yakbak');

// Ensure the tapes directory exists
const tapesDir = path.join(__dirname, 'tapes');
if (!fs.existsSync(tapesDir)) {
  fs.mkdirSync(tapesDir, { recursive: true });
}

// Create a yakbak handler for a dummy API endpoint
// We'll proxy to httpbin.org for demonstration
const handler = yakbak('https://httpbin.org', {
  dirname: tapesDir
});

// Create an HTTP server that uses the yakbak handler
const proxyServer = http.createServer((req, res) => {
  console.log(`Proxying request for: ${req.url}`);
  handler(req, res); // Yakbak handles the request (record or playback)
});

const PORT = 3000;
proxyServer.listen(PORT, () => {
  console.log(`Yakbak proxy server listening on http://localhost:${PORT}`);

  // Example client request to the yakbak proxy
  // This request will either be recorded or played back
  http.get(`http://localhost:${PORT}/get?foo=bar`, (response) => {
    let data = '';
    response.on('data', (chunk) => (data += chunk));
    response.on('end', () => {
      console.log('\n--- Client received response from Yakbak proxy ---');
      console.log(`Status: ${response.statusCode}`);
      console.log('Body:', JSON.parse(data));
      proxyServer.close(() => {
        console.log('Proxy server closed.');
        // Clean up tapes for repeated runs, if not desired to persist
        fs.rmdirSync(tapesDir, { recursive: true }); 
      });
    });
  }).on('error', (err) => {
    console.error('Client request error:', err);
    proxyServer.close();
    fs.rmdirSync(tapesDir, { recursive: true });
  });
});

view raw JSON →