Testing Cindel: Strategies for Unit and Widget Tests

Cindel is designed to be test-friendly. The Cindel.openInMemory API gives every test its own temporary database that uses the same generated typed API as your production code, so tests are fast, isolated, and trust-worthy. You don’t need a device, an emulator, or any disk setup — just the schemas your test cares about.

Unit and Package Tests

Open an in-memory database at the start of each test and register only the schemas that test needs:

void main() {
  late CindelDatabase db;

  setUp(() async {
    db = await Cindel.openInMemory(schemas: [TodoSchema]);
  });

  tearDown(() => db.close());

  test('creates and reads a todo', () async {
    final todo = Todo()..title = 'Test';
    await db.writeTxn(() => db.todos.put(todo));

    final found = await db.todos.where().findFirst();
    expect(found?.title, equals('Test'));
  });
}

Always call addTearDown(db.close) (or close in tearDown) so the database is cleaned up even when an expectation fails mid-test. On Web, openInMemory uses a unique browser database name for each session, so closing is especially important to avoid state leaking between test runs.

Give each test its own openInMemory instance rather than sharing a single database across tests. Isolated databases make failures easier to diagnose and prevent one test’s writes from affecting another.

What to Test

Cover the operations your application actually relies on:

CRUD — put, get, delete, putAll, getAll
Queries — where() helpers for indexed fields, filter() for arbitrary predicates
Aggregates — count() for pagination guards and empty-state logic
Sorting and pagination — verify that sort order and page limits produce the expected results

CRUD example

test('puts and gets a todo', () async {
  final db = await Cindel.openInMemory(schemas: [TodoSchema]);
  addTearDown(db.close);

  final todo = Todo()..title = 'Write docs';
  await db.writeTxn(() => db.todos.put(todo));

  final saved = await db.todos.get(todo.dbId);
  expect(saved, isNotNull);
  expect(saved!.title, 'Write docs');
});

Query example

test('filters open todos', () async {
  final db = await Cindel.openInMemory(schemas: [TodoSchema]);
  addTearDown(db.close);

  await db.writeTxn(() => db.todos.putAll([
    Todo()
      ..title = 'Open'
      ..completed = false,
    Todo()
      ..title = 'Done'
      ..completed = true,
  ]));

  final open = await db.todos
      .filter()
      .completedEqualTo(false)
      .findAll();

  expect(open, hasLength(1));
  expect(open.single.title, 'Open');
});

Count example

final count = await db.todos
    .filter()
    .completedEqualTo(false)
    .count();

expect(count, 1);

Use openInMemory inside testWidgets exactly as you would in a unit test. Pass the database to your widget tree and pump normally:

testWidgets('shows todos', (tester) async {
  final db = await Cindel.openInMemory(schemas: [TodoSchema]);
  addTearDown(db.close);

  await db.writeTxn(() => db.todos.put(Todo()..title = 'Write docs'));

  await tester.pumpWidget(
    TodoApp(database: db),
  );

  expect(find.text('Write docs'), findsOneWidget);
});

Keep database setup close to the test so each test controls its own data and there is no hidden shared state.

Keep cindel_flutter_libs in dependencies — not dev_dependencies — even when your tests use in-memory databases. This ensures integration tests and platform builds share the same package graph as the app, and that flutter test loads the native libraries correctly.

dependencies:
  cindel: ^x.y.z
  cindel_flutter_libs: ^x.y.z

Sync Testing

Test sync behavior with a FakeSyncAdapter that lets you control online/offline state deterministically. Toggle online before each assertion instead of relying on arbitrary sleep calls:

class FakeSyncAdapter implements CindelSyncAdapter {
  bool online = true;

  @override
  Future<CindelPushResult> push(CindelPushRequest request) async {
    if (!online) throw Exception('Offline');
    // ... handle push
  }

  @override
  Future<CindelPullResult> pull(CindelPullRequest request) async {
    if (!online) throw Exception('Offline');
    // ... handle pull
  }
}

Wire the fake adapter into a database opened with a real directory (not in-memory, so you can test close/reopen and persistence), and use a short sync interval to keep tests fast:

final adapter = FakeSyncAdapter()..online = false;
final statuses = <CindelSyncStatus>[];

final db = await Cindel.open(
  directory: directory.path,
  schemas: [UserSchema],
  sync: CindelSyncConfig(
    adapter: adapter,
    interval: const Duration(milliseconds: 10),
    onStatusChanged: statuses.add,
  ),
);

Useful sync cases to cover:

A local write is visible immediately, even while offline
A pending write survives close and reopen
A backend correction applies locally after the adapter comes back online
A delete replicates to another client
A remote apply does not create a second local pending mutation
Unsupported operations fail with a clear error

When to Use a Persistent Temp Directory

Use openInMemory for the vast majority of your tests. Reach for a persistent temporary directory (for example, via path_provider’s temp dir) only when the test specifically needs:

Close/reopen behavior — verify data survives a database restart
File persistence — check that files appear on disk after a write
Backup and restore — test full archive export/import flows
Sync restart behavior — confirm pending mutations survive a process restart

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Testing Cindel: Strategies for Unit and Widget Tests

Unit and Package Tests

What to Test

Widget Tests

Sync Testing

When to Use a Persistent Temp Directory

​Unit and Package Tests

​What to Test

​Widget Tests

​Sync Testing

​When to Use a Persistent Temp Directory

Unit and Package Tests

What to Test

Widget Tests

Sync Testing

When to Use a Persistent Temp Directory