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.

This package is an indirect development dependency for driver authors, not an application runtime package. Applications should use ormed with a runtime driver such as ormed_sqlite, ormed_postgres, or ormed_mysql.

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():

Suite	Description
Query Tests	Filtering, ordering, pagination, statement previews
Join Tests	Inner/outer joins, join builders, relation aliases
Advanced Query Tests	Between, in/notIn, null predicates
Mutation Tests	Insert/update/delete round trips, upsert
Transaction Tests	Rollback on exception, commit on completion
Repository Tests	Full repository operations (CRUD, DTOs, Maps)
Driver Override Tests	Custom codec/driver behavior overrides
Model Event Cancel Tests	Event cancellation during model lifecycle
Factory Inheritance Tests	Model factory inheritance patterns
Partial Entity Tests	Partial class validation, toEntity()

Query Builder Tests (29 sub-suites)

Category	Tests
Clauses	WHERE, ORDER BY, LIMIT/OFFSET, SELECT, JOIN
Aggregation	count, sum, avg, min, max
Relations	Lazy loading, aggregates, mutations, caching
CRUD	Create, read, update, delete, upsert, batch
Refresh/Sync	refresh, fresh, queryrow sync, replication
Advanced	JSON queries, date/time, subqueries, scopes
Utilities	Raw queries, chunking/streaming, caching, timestamps

Test Models

The package includes 20+ test models with migrations:

Model	Purpose
User, UserProfile	Basic user with hasOne relationship
Author, Post, Tag, PostTag	Blog-style relations (hasMany, belongsToMany)
Article	Rich model with ratings, status, nullable fields
Comment	Soft-delete enabled model
Photo, Image	Polymorphic relationships
ScopedUser, UniqueUser	Scopes and unique constraints
CustomSoftDelete, EventModel	Lifecycle events

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

Related packages

Package	Use it for
ormed	Core runtime and application APIs
ormed_sqlite	SQLite driver under test
ormed_postgres	PostgreSQL driver under test
ormed_mysql	MySQL/MariaDB driver under test

Libraries

driver_tests

models

orm_registry.g

seeders