driver_tests #

Shared, driver-agnostic integration test suite for the ormed ORM. These test suites assert baseline query, mutation, and transaction behaviors that every database driver must satisfy.

Purpose #

Individual driver packages (ormed_sqlite, ormed_postgres, ormed_mysql) include this package as a dev_dependency, supply their own test harness, and run the shared suites. This ensures consistent behavior across all supported databases.

Installation #

dev_dependencies:
  driver_tests:
    path: ../driver_tests  # or workspace resolution

Usage #

1. Create a Test Harness #

Each driver package creates a harness that bootstraps the ORM:

import 'package:driver_tests/driver_tests.dart';
import 'package:ormed_sqlite/ormed_sqlite.dart';

Future<void> createSqliteTestHarness() async {
  final adapter = SqliteDriverAdapter.inMemory();
  
  await setUpOrmed(
    adapter: adapter,
    migrations: allMigrationDescriptors,
    isolationStrategy: DatabaseIsolationStrategy.migrateWithTransactions,
  );
}

2. Run Shared Tests #

import 'package:driver_tests/driver_tests.dart';
import 'package:test/scaffolding.dart';

Future<void> main() async {
  final harness = await createSqliteTestHarness();
  tearDownAll(() => harness.dispose());
  
  // Run all shared test suites
  runAllDriverTests();
}

Test Suites #

The package provides 13 main test suites via runAllDriverTests():

Query Builder Tests (29 sub-suites) #

Test Models #

The package includes 20+ test models with migrations:

Driver Configuration #

Drivers declare capabilities via DriverTestConfig:

final config = DriverTestConfig(
  supportsReturning: true,
  supportsJoins: true,
  supportsRightJoin: true,
  supportsDistinctOn: false,  // SQLite doesn't support DISTINCT ON
  supportsTransactions: true,
);

Tests automatically skip when a capability is not supported:

if (!metadata.supportsCapability(DriverCapability.transactions)) {
  return; // Skip transaction tests
}

Database Isolation #

Tests use ormedGroup() for per-test database isolation:

ormedGroup('My feature tests', () {
  test('should work correctly', () async {
    final ds = await getDataSource();
    // Each test gets a clean database state
  });
});

Isolation strategies:

• migrate - Run migrations for each test
• migrateWithTransactions - Migrations + transaction rollback
• truncate - Truncate tables between tests
• recreate - Drop and recreate database

Seeders #

Pre-built seeders for test data:

import 'package:driver_tests/seeders.dart';

await UserSeeder().run();
await AuthorSeeder().run();

Directory Structure #

lib/
├── driver_tests.dart      # Main exports
├── models.dart            # Model exports
├── seeders.dart           # Seeder exports
├── orm_registry.g.dart    # Generated registry
└── src/
    ├── config.dart        # DriverTestConfig
    ├── migrations/        # 19 table migrations
    ├── models/            # 20+ model definitions
    ├── support/           # Schema/seeder helpers
    └── tests/             # Test suites
        ├── all_tests.dart
        └── query_builder/ # 29 QB test files