Testing

A test class marked @DataTest() starts only the data layer of the application: its repositories and data beans, an in-memory SQLite database with your migrations applied, and a transaction around every test that is rolled back afterwards. Services, controllers and runners are not in the context. spring_boot_starter_test runs it.

Why

A repository test needs the repositories, a real database and a clean slate for every test. Starting the whole application is slow and brings beans the test does not need; sharing data between tests makes them depend on their order. @DataTest is Spring's @DataJdbcTest with @AutoConfigureTestDatabase: a small context, a fresh database, and a rollback after each test.

Example

# pubspec.yaml
dependencies:
  spring_boot_starter_data: ^0.9.0
  sqlite3: ^3.8.0                     # required: the test database is SQLite

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
  spring_boot_starter_test: ^0.9.0
  test: ^1.33.0
// test/book_repository_test.dart
import 'package:spring_boot_starter_data/spring_boot_starter_data.dart';
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:test/test.dart';

import 'spring_gen/book_repository.test.spring.dart'; // generated

@DataTest()
class BookRepositoryTest {
  @Autowired()
  late BookRepository books;

  @BeforeEach()
  Future<void> seed() async {                     // runs inside the test's transaction
    await books.save(Book(title: 'Dune', year: 1965));
  }

  @Test()
  Future<void> findsABookByItsTitle() async {
    await books.save(Book(title: 'Emma', year: 1815));
    expect(await books.findByTitle('Emma'), hasLength(1));
  }                                               // rolled back

  @Test()
  Future<void> startsWithTheSeedOnly() async {
    expect(await books.count(), 1);               // no 'Emma' from the test before
  }
}

void main() => runSpringTests();
dart run build_runner build    # writes test/spring_gen/book_repository.test.spring.dart
dart test

The class is written like a @SpringBootTest one: @Autowired() fields, @Test() methods, @BeforeEach, @Nested, @ActiveProfiles, @TestPropertySource and @TestBean work the same. A class has @SpringBootTest() or @DataTest(), not both.

What the context holds

The database

When the application configures a SQL database, @DataTest replaces it with an in-memory SQLite database before the context starts:

Property Set to Why
spring.datasource.url sqlite::memory: The database lives as long as its connection.
spring.datasource.driver sqlite3 Whatever the configuration named.
spring.datasource.pool.max-size 1 Each SQLite connection has its own in-memory database.
spring.datasource.pool.min-idle, idle-timeout, max-lifetime 0 The pool never closes the one connection and loses the data.

Every other setting stays, and the same happens to each spring.datasources.<name>.url. Without a configured database nothing is replaced: the repositories use the in-memory store, as in the application.

The schema comes from where it comes from in the application: migrations are applied (and the entities validated), or schema.sql and data.sql run, or, without either, the tables are created from the entities.

The transaction

Each test runs in a transaction of every transaction manager its repositories write through (the primary database's, the in-memory store's, the named databases'), rolled back at its end.

Options

Option Default Meaning
application the package's only application The application whose beans are used (Spring's classes).
args [] Command line arguments.
properties {} Properties for the test.
resourceDirectories ['test/resources'] Extra resource directories.
include [] Beans of the application to add, by type.
replaceDatabase true Replace the configured database with an in-memory SQLite one.
transactionManager '' The one manager whose transaction the tests run in; empty for every manager the repositories use.

Tests written as functions

DataTestSetup and runInTestTransaction, from package:spring_boot_starter_data/testing.dart, do the same without a class:

import 'package:spring_boot_starter_data/testing.dart';

void main() {
  final data = DataTestSetup(springApplication);
  final app = springBootTest(
    springApplication,
    properties: data.properties,        // other starters' auto-configuration out
    initializers: [data.initializer],   // database replaced, beans left out
  );

  test('finds a book', () => runInTestTransaction(app.context, () async {
    final books = app.getBean<BookRepository>();
    await books.save(Book(title: 'Dune', year: 1965));
    expect(await books.findByTitle('Dune'), hasLength(1));
  }));
}

In Spring (Java)

@DataJdbcTest
class BookRepositoryTest {
  @Autowired BookRepository books;

  @Test void findsABookByItsTitle() { ... }
}

@DataTest replaces @DataJdbcTest with @AutoConfigureTestDatabase. It is transactional by itself, and the test database is always an in-memory SQLite one (replaceDatabase: false keeps yours). A failing @Commit test is rolled back.

See also