testing library

Provides utilities for testing ORM applications.

This library includes helpers for database isolation, lifecycle management, and automated migrations during tests.

Key features:

• TestDatabaseManager for managing test database lifecycles.
• ormedGroup and ormedTest for isolated test definitions.
• Support for multiple isolation strategies (transactions, truncation, recreation).

For a detailed guide on testing, see the Testing Guide.

Basic Usage

import 'package:ormed/testing.dart';

void main() {
  setUpOrmed(
    dataSource: myDataSource,
    migrations: [CreateUsersTable()],
  );

  ormedGroup('User tests', (ds) {
    ormedTest('can create user', (ds) async {
      final user = await ds.repo<User>().insert(User(name: 'Alice'));
      expect(user.id, isNotNull);
    });
  });
}

Classes

DatabaseSeeder

Base class for database seeders that work with OrmConnection

OrmedTestConfig

Global test counter for unique IDs Configuration object returned by setUpOrmed. Pass this to ormedGroup to ensure the correct manager is used.

Seeder

Base class for database seeders

SeederRegistration

Seeder registration for managing multiple seeders.

SeederRegistry

Registry and runner for database seeders

TestDatabaseManager

Manages the lifecycle and isolation of test databases.

TestSchemaManager

Manages test schema setup with migrations and seeding support

Enums

DatabaseIsolationStrategy

Defines strategies for database isolation in tests.

Extensions

DataSourceSeeding on DataSource

Extension on DataSource for convenient seeding

SchemaDriverTestExtensions on SchemaDriver

Extension to add test schema management to SchemaDriver

Properties

currentTestDataSource → DataSource?

Get the current test data source (valid inside ormedGroup/ormedTest)

no setter

testDatabaseManager → TestDatabaseManager?

Get current test database manager

no setter

Functions

ormedGroup(String description, void body(DataSource dataSource), {OrmedTestConfig? config, DataSource? dataSource, List<Migration>? migrations, DatabaseRefreshStrategy? refreshStrategy, String? testOn, Timeout? timeout, dynamic skip, dynamic tags, Map<String, dynamic>? onPlatform, int? retry}) → void

Runs a test group with database isolation.

ormedTest(String description, FutureOr<void> body(DataSource dataSource), {String? testOn, Timeout? timeout, dynamic skip, dynamic tags, Map<String, dynamic>? onPlatform, int? retry}) → void

Runs a test with database isolation.

previewTestSeed(List<DatabaseSeeder Function(OrmConnection)> seeders, DataSource dataSource) → Future<List<QueryLogEntry>>

Preview seeder queries without executing them

runSeederRegistry(OrmConnection connection, List<SeederRegistration> seeders, {List<String>? names, bool pretend = false, void log(String message)?}) → Future<void>

Run registered seeders on a connection

seedTestData(List<DatabaseSeeder Function(OrmConnection)> seeders, DataSource dataSource) → Future<void>

Seed data in the current test environment

setUpOrmed({required DataSource dataSource, Future<void> runMigrations(DataSource)?, List<Migration>? migrations, List<MigrationDescriptor>? migrationDescriptors, List<DatabaseSeeder Function(OrmConnection)>? seeders, DatabaseIsolationStrategy strategy = DatabaseIsolationStrategy.migrateWithTransactions, bool parallel = false, DriverAdapter adapterFactory(String testDbName)?}) → OrmedTestConfig

Configures Ormed for testing.

testMigrationStatus(DataSource dataSource) → Future<List<MigrationStatus>>

Get migration status in the test environment

Typedefs

DatabaseRefreshStrategy = DatabaseIsolationStrategy

Re-export DatabaseIsolationStrategy as DatabaseRefreshStrategy for backwards compatibility