flutter_mockkit #

A lightweight, developer-friendly toolkit to mock API requests and responses in Flutter apps during development.

Stop waiting for a backend. With flutter_mockkit you can:

• Intercept every HTTP call from http and dio clients.
• Return static or dynamically computed responses.
• Simulate realistic network latency and hard failures.
• Toggle between mock and live mode with a single line of code.
• Generate realistic fake data from a JSON schema — no extra dependencies.

Table of Contents #

1. Features
2. Installation
3. Quick Start
4. Usage Guide
   • Enabling / Disabling Mock Mode
   • Basic GET Mock
   • Basic POST Mock
   • Dynamic Responses
   • Path Parameters
   • Simulated Latency
   • Error Simulation
   • Network Failure Simulation
   • Using with http package
   • Using with dio
   • Auto-Generating Mock Data
   • Verbose Logging
5. API Reference
6. Publishing to pub.flutter-io.cn
7. Contributing
8. License

Features #

Installation #

Add flutter_mockkit to your pubspec.yaml:

dependencies:
  flutter_mockkit: ^1.0.0

Then run:

flutter pub get

Tip: Consider adding this only to dev_dependencies if you wrap the mock setup behind a build-time flag so mocks are never shipped to production.

Quick Start #

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

void main() {
  // 1. Enable mock mode
  MockKit.enable();

  // 2. Register a mock route
  MockKit.register(MockRoute(
    method: HttpMethod.get,
    path: '/users',
    response: MockResponse.ok({'users': [{'id': 1, 'name': 'Alice'}]}),
  ));

  // 3. Attach the interceptor to your Dio client
  final dio = Dio(BaseOptions(baseUrl: 'https://api.example.com'));
  dio.interceptors.add(MockDioInterceptor());

  runApp(MyApp(dio: dio));
}

That's it — every GET /users call now returns your mock data, zero network traffic involved.

Usage Guide #

1. Enabling / Disabling Mock Mode #

// Enable – all registered mocks are active
MockKit.enable();

// Disable – requests pass through to the real network
MockKit.disable();

// Check current state
print(MockKit.isEnabled); // true / false

A common pattern is to gate this on your build mode:

if (kDebugMode) MockKit.enable();

2. Basic GET Mock #

MockKit.register(MockRoute(
  method: HttpMethod.get,
  path: '/products',
  description: 'Returns the product catalogue', // optional — for your notes
  response: MockResponse.ok([
    {'id': 1, 'name': 'Widget A', 'price': 9.99},
    {'id': 2, 'name': 'Widget B', 'price': 19.99},
  ]),
));

Convenience response factories:

MockResponse.ok(body)            // 200
MockResponse.created(body)       // 201
MockResponse.badRequest()        // 400
MockResponse.unauthorized()      // 401
MockResponse.notFound()          // 404
MockResponse.serverError()       // 500
MockResponse.networkFailure()    // throws MockNetworkException

3. Basic POST Mock #

MockKit.register(MockRoute(
  method: HttpMethod.post,
  path: '/products',
  response: MockResponse.created({'id': 42, 'name': 'New Widget'}),
));

4. Dynamic Responses #

Use a responseBuilder to inspect the request before deciding what to return. The builder receives a MockRequest with body, queryParameters, headers, and pathParameters already parsed.

MockKit.register(MockRoute(
  method: HttpMethod.post,
  path: '/login',
  responseBuilder: (request) {
    final body = request.bodyAsJson; // Map<String, dynamic>

    if (body['password'] == 'secret') {
      return MockResponse.ok({'token': 'jwt-abc-123'});
    }

    return MockResponse.unauthorized();
  },
));

5. Path Parameters #

Routes support :name style path parameters. They are extracted and passed into MockRequest.pathParameters.

// Route: /users/:id
MockKit.register(MockRoute(
  method: HttpMethod.get,
  path: '/users/:id',
  responseBuilder: (request) {
    final id = request.pathParameters['id']!; // '42'
    return MockResponse.ok({'id': id, 'name': 'User $id'});
  },
));

// Matches:
//   GET /users/1
//   GET /users/42
//   GET /users/abc123

Multi-segment parameters also work:

MockKit.register(MockRoute(
  method: HttpMethod.get,
  path: '/teams/:teamId/members/:memberId',
  responseBuilder: (request) {
    return MockResponse.ok({
      'team': request.pathParameters['teamId'],
      'member': request.pathParameters['memberId'],
    });
  },
));

6. Simulated Latency #

Per-route delay

MockKit.register(MockRoute(
  method: HttpMethod.get,
  path: '/reports/annual',
  response: MockResponse.ok(
    {'report': 'data…'},
    delay: const Duration(seconds: 2), // simulate a slow query
  ),
));

Global delay (added to every response)

// Add 300 ms to every mock response — great for testing loading states
MockKit.setGlobalDelay(const Duration(milliseconds: 300));

7. Error Simulation #

Return any 4xx / 5xx status code to test your error-handling UI:

// 503 Service Unavailable
MockKit.register(MockRoute(
  method: HttpMethod.get,
  path: '/maintenance',
  response: MockResponse(
    statusCode: 503,
    body: {'message': 'Under maintenance'},
  ),
));

Use the built-in factories for the most common cases:

MockResponse.notFound()      // 404 {"error": "Not Found"}
MockResponse.serverError()   // 500 {"error": "Internal Server Error"}
MockResponse.unauthorized()  // 401 {"error": "Unauthorized"}

8. Network Failure Simulation #

Simulates a hard network failure (throws an exception rather than returning an HTTP response):

MockKit.register(MockRoute(
  method: HttpMethod.get,
  path: '/flaky-endpoint',
  response: MockResponse.networkFailure(
    message: 'No internet connection',
  ),
));

With MockHttpClient this throws a MockNetworkException. With MockDioInterceptor this triggers a DioException.

Handle it the same way you would handle a real network error:

try {
  final response = await dio.get('/flaky-endpoint');
} on DioException catch (e) {
  showErrorSnackBar('Network error: ${e.message}');
}

9. Using with the http Package #

Replace http.Client() with MockHttpClient() — the API is identical:

import 'package:http/http.dart' as http;
import 'package:flutter_mockkit/flutter_mockkit.dart';

final http.Client client = MockHttpClient();

final response = await client.get(
  Uri.parse('https://api.example.com/users'),
);

print(response.statusCode); // 200
print(response.body);       // {"users": [...]}

When MockKit.isEnabled is false, or when no matching route is found, every request is forwarded to the real network via the inner http.Client.

10. Using with Dio #

Add MockDioInterceptor as the first interceptor on your Dio instance:

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

final dio = Dio(BaseOptions(baseUrl: 'https://api.example.com'));
dio.interceptors.add(MockDioInterceptor()); // ← add first

final response = await dio.get('/users');
print(response.data); // already decoded JSON

When mock mode is disabled or no route matches, MockDioInterceptor calls handler.next(options) and Dio proceeds normally.

11. Auto-Generating Mock Data #

MockDataGenerator turns a simple schema map into realistic fake data.

Single object

final user = MockDataGenerator.fromSchema({
  'id':       'uuid',
  'name':     'name',
  'email':    'email',
  'phone':    'phone',
  'age':      'int',
  'score':    'double',
  'active':   'bool',
  'joined':   'date',
  'profile':  'url',
  'bio':      'paragraph',
});
// {id: 'a1b2…', name: 'Alice Chen', email: 'alice.chen@example.com', …}

Supported type strings:

List of objects

final users = MockDataGenerator.listFromSchema(
  {'id': 'uuid', 'name': 'name', 'email': 'email'},
  count: 10,
);

Paginated response

final page = MockDataGenerator.paginatedList(
  schema: {'id': 'uuid', 'title': 'string', 'price': 'double'},
  page: 2,
  perPage: 10,
  total: 57,
);
// {
//   "data": [{…}, {…}, …],
//   "pagination": {
//     "page": 2, "per_page": 10, "total": 57,
//     "total_pages": 6, "has_next": true, "has_prev": true
//   }
// }

Wrap existing JSON as a MockResponse

final response = MockDataGenerator.fromJson(
  {'token': 'eyJhbGci…', 'expires_in': 3600},
  statusCode: 200,
  delay: const Duration(milliseconds: 200),
);

Individual primitive generators

MockDataGenerator.uuid();                              // "f47ac10b-…"
MockDataGenerator.name();                              // "James Lopez"
MockDataGenerator.email();                             // "james.lopez@test.dev"
MockDataGenerator.phone();                             // "+1-303-721-4892"
MockDataGenerator.date();                              // "2021-03-18"
MockDataGenerator.datetime();                          // "2021-03-18T14:22:00.000"
MockDataGenerator.url();                               // "https://mockserver.io/api/v1/…"
MockDataGenerator.hexColor();                          // "#E4A0F7"
MockDataGenerator.paragraph();                         // "Lorem ipsum dolor…"
MockDataGenerator.randomInt(min: 1, max: 100);         // 57
MockDataGenerator.randomDouble(min: 0.0, max: 10.0);   // 3.74
MockDataGenerator.randomBool();                        // false
MockDataGenerator.pickOne(['a', 'b', 'c']);            // "b"

12. Verbose Logging #

Enable during development to see every intercepted call in the console:

MockKit.enableLogging();

// Console output:
// [MockKit] Registered mock: GET /users
// [MockKit] [MOCK] GET /users → 200
// [MockKit] [FAIL] GET /network-failure → Simulated network failure

API Reference #

MockKit #

MockRoute #

MockRoute({
  required HttpMethod method,
  required String path,       // supports :param notation
  MockResponse? response,
  MockResponse Function(MockRequest)? responseBuilder,
  String? description,
})

MockResponse #

MockResponse({
  int statusCode = 200,
  dynamic body,
  Map<String, String> headers,
  Duration delay = Duration.zero,
  bool shouldFail = false,
  String? failureMessage,
})

Factory constructors: ok, created, badRequest, unauthorized, notFound, serverError, networkFailure.

MockRequest #

MockDataGenerator #

Static utility — no instantiation required.

Publishing to pub.flutter-io.cn #

Follow these steps to publish flutter_mockkit to pub.flutter-io.cn:

1. Prerequisites #

• Dart SDK ≥ 3.0 installed.
• A Google account linked to pub.flutter-io.cn.

2. Update pubspec.yaml #

Edit the following fields before publishing:

name: flutter_mockkit
version: 1.0.0                              # ← bump on each release
homepage: https://github.com/YOU/flutter_mockkit
repository: https://github.com/YOU/flutter_mockkit

3. Verify the package #

dart pub publish --dry-run

Fix every warning/error reported. Common issues:

4. Check your pub score locally #

dart pub global activate pana
pana .

Aim for 130/140 or higher before publishing.

5. Publish #

dart pub publish

You will be prompted to authenticate via your browser.

6. Subsequent releases #

1. Update version in pubspec.yaml.
2. Add a new entry to CHANGELOG.md.
3. Run dart pub publish --dry-run again.
4. Run dart pub publish.

Contributing #

Contributions, bug reports and feature requests are welcome!

1. Fork the repo.
2. Create a branch: git checkout -b feat/my-feature.
3. Commit your changes: git commit -m 'feat: add my feature'.
4. Push: git push origin feat/my-feature.
5. Open a Pull Request.

Please run flutter test and dart analyze before submitting a PR.

License #

This project is licensed under the MIT License.