MockBeam Record

Never write a mock response by hand again.

MockBeam Record is a Dart CLI proxy that sits between your Flutter app and your real backend, captures every JSON response, deduplicates by endpoint, and writes a YAML file that drops straight into dio_mock_interceptor — the most popular Flutter mock package on pub.dev.

The problem

Every Flutter mock package shares the same flaw: you have to write the mock responses yourself. That means:

  • Manually inspecting network calls in DevTools or Postman
  • Copy-pasting JSON into config files
  • Updating mocks every time the real API changes
  • Discovering missing edge cases as bugs in production

The real API already has all the responses. There is no reason to retype them.

Install

dart pub global activate mockbeam_record

30-second quickstart

# 1. Start the proxy
mockbeam_record record --target https://api.yourapp.com

# 2. Point your Flutter app at the proxy — no code changes needed:
#    flutter run --dart-define=BASE_URL=http://localhost:8080

# 3. Use your app normally for a few minutes (open screens, log in, etc.)

# 4. Press Ctrl+C

MockBeam Record v1.0.0
Proxying https://api.yourapp.com → localhost:8080

Waiting for requests... (Ctrl+C to stop and save)

  ✓  GET    /users/me                      200  142ms
  ✓  GET    /users/1/posts                 200   89ms
  ✓  POST   /auth/refresh                  200  201ms
  ✓  GET    /notifications                 200   67ms
  ⚠  GET    /avatar.png                    200  [binary — skipped]
  ✓  GET    /notifications                 200  [duplicate — skipped]

Stopping...
4 routes captured.
Wrote mocks/recorded.yaml

Open mocks/recorded.yaml — it is already in dio_mock_interceptor format.

Configure your Flutter app

Add one build-flag switch so you can toggle proxy mode without changing code:

// lib/core/constants.dart
const baseUrl = String.fromEnvironment(
  'BASE_URL',
  defaultValue: 'https://api.yourapp.com',
);

# During recording sessions:
flutter run --dart-define=BASE_URL=http://localhost:8080

# Normal development / production — nothing changes:
flutter run

Sample output

# Generated by MockBeam Record v1.0.0
# Target: https://api.yourapp.com
# Recorded: 2026-05-08T14:32:00Z

- path: /users/me
  method: GET
  statusCode: 200
  data:
    id: 1
    name: "Anuj Gupta"
    email: "anuj@example.com"

- path: /users/1/posts
  method: GET
  statusCode: 200
  data:
    - id: 101
      title: "First post"
    - id: 102
      title: "Second post"

- path: /auth/refresh
  method: POST
  statusCode: 200
  data:
    token: "eyJhbGciOiJIUzI1NiJ9..."
    expiresIn: 3600

Use with dio_mock_interceptor

# pubspec.yaml
dependencies:
  dio_mock_interceptor: ^<latest>

flutter:
  assets:
    - mocks/recorded.yaml

import 'package:dio/dio.dart';
import 'package:dio_mock_interceptor/dio_mock_interceptor.dart';

final dio = Dio(BaseOptions(baseUrl: 'https://api.yourapp.com'));

// Swap in during development/testing:
dio.interceptors.add(
  DioMockInterceptor(
    mockData: MockData.fromAsset('mocks/recorded.yaml'),
  ),
);

All options

Flag Default Description
-t, --target (required) Upstream base URL to proxy
-p, --port 8080 Local port to listen on
-o, --out mocks/recorded.yaml Output file path
-f, --format yaml Output format: yaml or json
--filter — Glob — only capture matching paths (e.g. /api/*)
-k, --insecure — Skip TLS certificate verification for HTTPS targets
--capture-errors — Also capture 4xx and 5xx responses
-a, --append — Merge new routes into an existing output file
--version — Print version and exit
--help — Print usage and exit

Common recipes

# Only capture your API endpoints, ignore static assets
mockbeam_record record --target https://api.yourapp.com --filter '/api/**'

# Record against a staging server with a self-signed cert
mockbeam_record record --target https://staging.yourapp.com --insecure

# Append to an existing file across multiple sessions
mockbeam_record record --target https://api.yourapp.com --append

# Output JSON instead of YAML
mockbeam_record record --target https://api.yourapp.com --format json --out mocks/recorded.json

# Capture error responses too (useful for error-state UI testing)
mockbeam_record record --target https://api.yourapp.com --capture-errors

Use cases

Scenario How MockBeam helps
Bootstrap a new project Backend API exists but isn't stable. Record one session; develop offline from that point.
Reproduce a bug The exact response that caused it is in recorded.yaml. Iterate on the fix against the real shape.
Demo prep Record against staging, enable mock mode, demo runs perfectly offline.
Onboard a new developer Share recorded.yaml. New dev runs the full app on day one without API keys.
Generate test fixtures QA gets real response shapes, not hand-crafted approximations.

How it works

Flutter App  →  localhost:8080  →  MockBeam Proxy  →  Real API
                                         │
                              Capture if JSON (deduplicate)
                                         │
                              Ctrl+C  →  recorded.yaml

MockBeam is a standard HTTP forward proxy built on dart:io's HttpServer and HttpClient — no extra HTTP dependencies. Every request is forwarded transparently; the app cannot tell the proxy is there. On Ctrl+C, captured routes are written atomically (write to .tmp, rename) so the file is never partially written.

Deduplication key is method:path, ignoring query strings, so paginated endpoints like /posts?page=1 and /posts?page=2 produce a single mock entry.

Known limitations (v1)

  • Binary responses (images, PDFs) are skipped — they don't produce useful mocks.
  • HTTPS certificate injection is not supported — use --insecure for dev.
  • No WebSocket or gRPC recording.
  • No auth token scrubbing — review recorded.yaml before committing.
  • One --target per session — run separate sessions for multiple backends.
  • No stateful response sequences — same endpoint always returns the first recorded response.

Security

⚠️ Warning: recorded.yaml may contain authentication tokens, personal data, or other sensitive values from real API responses. MockBeam does not scrub sensitive fields.

# Add to your project's .gitignore immediately:
echo "mocks/recorded.yaml" >> .gitignore

--insecure disables TLS certificate verification. Only use it on trusted networks against non-production endpoints.

License

MIT — © 2026 Anuj Gupta

Libraries

mockbeam_record
MockBeam Record — programmatic API for embedding the proxy in other tools.