Flutter Fixtures SQLite #

SQLite/sqflite implementation for the Flutter Fixtures library. Mock database queries with fixture files for testing and development.

🎯 Purpose #

This package provides a fixture-backed DatabaseAdapter for SQLite, allowing you to:

• Mock database queries during development and testing
• Test different data scenarios without modifying the database
• Develop UI features before the database schema is finalized
• Create reproducible test scenarios

📦 What's Included #

FixtureDatabase #

A drop-in replacement for sqflite's Database that returns fixture data. Provides the same familiar API (query, insert, update, delete) so you can swap between fixture and real databases easily.

SqfliteFileFixtureSource #

The file-backed SqfliteFixtureSource (core's FixtureSource<SqfliteQuery>): loads fixture files from your app's assets and returns them as fixture collections. Implement FixtureSource<SqfliteQuery> yourself to provide fixtures from anywhere else.

StatementDatabaseAdapter #

The base every adapter extends: the nine sqflite-shaped operations are translated into a SqfliteQuery statement once, and an adapter implements a single run(statement). RealDatabaseAdapter, FixtureDatabaseAdapter and RecorderDatabaseAdapter are each one run; so is a custom adapter (a canned-rows fake, a logging decorator).

SqfliteQuery #

A model class representing database queries for fixture matching.

🚀 Installation #

Add the package to your pubspec.yaml:

dependencies:
  flutter_fixtures_sqflite: ^0.3.0
  sqflite: ^2.4.1

📁 Fixture File Structure #

Create fixture files in assets/fixtures/database/ directory:

assets/
  fixtures/
    database/
      query_users.json
      query_products.json
      insert_orders.json

Fixture File Format #

{
  "description": "User table query fixtures",
  "values": [
    {
      "identifier": "success",
      "description": "Returns list of users",
      "default": true,
      "data": [
        {"id": 1, "name": "John", "email": "john@example.com"},
        {"id": 2, "name": "Jane", "email": "jane@example.com"}
      ]
    },
    {
      "identifier": "empty",
      "description": "Returns empty result",
      "data": []
    },
    {
      "identifier": "single",
      "description": "Returns single user",
      "data": [
        {"id": 1, "name": "John", "email": "john@example.com"}
      ]
    }
  ]
}

💡 Usage #

Using FixtureDatabase (Recommended) #

Use FixtureDatabaseAdapter as a drop-in replacement for sqflite's Database:

import 'package:flutter_fixtures_sqflite/flutter_fixtures_sqflite.dart';
import 'package:flutter_fixtures_core/flutter_fixtures_core.dart';

// Create a fixture database (same API as sqflite's Database)
final db = FixtureDatabaseAdapter(
  pipeline: FixturePipeline(
    source: SqfliteFileFixtureSource(),
    selector: DataSelectorType.defaultValue,
  ),
);

// Query just like a real sqflite database!
final users = await db.query('users');
final products = await db.query('products', where: 'category = ?');

// Insert, update, delete also work
final id = await db.insert('users', {'name': 'John', 'email': 'john@example.com'});
await db.update('users', {'name': 'Jane'}, where: 'id = ?');
await db.delete('users', where: 'id = ?');

With Interactive Fixture Selection #

FixturesDialogView comes from the flutter_fixtures_ui package — add it to your dev dependencies alongside this one.

// Build the pipeline once, for the lifetime you want choices remembered.
final db = FixtureDatabaseAdapter(
  pipeline: FixturePipeline(
    source: SqfliteFileFixtureSource(),
    selector: DataSelectorType.pick,
    view: FixturesDialogView.of(context),
    delay: DataSelectorDelay.fast,
  ),
);

// When querying, a dialog will let you pick which fixture to return
final users = await db.query('users');

Low-Level API #

For more control, use SqfliteFileFixtureSource directly:

final dataQuery = SqfliteFileFixtureSource();

// Create a query
final query = SqfliteQuery.table(
  table: 'users',
  operation: SqfliteOperation.query,
);

// Find and parse fixtures
final collection = await source.resolve(query);
if (fixtureData != null) {
  final collection = await dataQuery.parse(fixtureData);
  final selected = await dataQuery.select(
    collection!,
    null,
    DataSelectorType.defaultValue,
  );
  final result = await dataQuery.data(selected!);
  print(result);
}

File Naming Convention #

Files should be named based on the query operation and table:

🔗 Related Packages #

• flutter_fixtures: Complete Flutter Fixtures library
• flutter_fixtures_core: Core interfaces and models
• flutter_fixtures_dio: Dio HTTP client implementation
• flutter_fixtures_ui: UI components for fixture selection

📄 License #

MIT License - see LICENSE for details.

Record & replay #

This package also ships RecorderDatabaseAdapter, a record & replay decorator over any DatabaseAdapter: capture real query results and mutations while exercising the app, then replay them later in recorded order — without touching the database. The engine and UI tools live in flutter_fixtures_recorder; this adapter only talks to the thin TrafficRecorder seam in core.

final db = RecorderDatabaseAdapter(
  inner: RealDatabaseAdapter(await openDatabase("app.db")),
  recorder: recorder,
);

See the recorder package README for sessions, storage, and ordering semantics.