Getting Started

Install the package and extend its PackageTestCase in your package’s test suite.
Start by checking migrationSources() in your test case. Return the paths to your package migrations (e.g. __DIR__.'/../database/migrations').
First use case: write a test that touches the database. The base class migrates your sources and resets the database between tests. If your package has no migrations, leave migrationSources() empty—tests still run with a drop-per-test reset.

Implementation Patterns

Packages with migrations: override migrationSources() and call keepsMigratedSchema() in setUp() to migrate once and reuse the schema across tests for speed.
Packages without migrations: do not call keepsMigratedSchema(). Rely on the default drop-per-test reset, and build any fixture tables inside individual tests.
Mixed manual fixtures and migrations: keepsMigratedSchema() snapshots only the migrated schema. Tables you create by hand in a test are not preserved and are dropped before the next test.
Custom migration discovery: override migrationSources() to return an array of paths. An empty array is valid and, since 1.6.1, safe to use with keepsMigratedSchema().

Before 1.6.1, calling keepsMigratedSchema() with an empty migrationSources() caused every database test to fail with no such table: migrations. Upgrade to 1.6.1+ if you have such test cases.
keepsMigratedSchema() only keeps a schema snapshot when a migrations table exists after migrating. With no migrations, it keeps nothing and the test case stays on the drop-per-test reset.
Manual fixture tables are always dropped before the next test, even when keepsMigratedSchema() is called, because they are not part of the schema snapshot.
Debugging: if you see no such table: migrations, check whether a test case calls keepsMigratedSchema() without any migration sources. Either remove the call or add sources.
Extension point: override migrationSources() to control migration discovery; return an empty array when your package has no migrations.