Testing

How to run unit tests, E2E tests, and coverage reports across all ReadRealm apps — backend, dashboard, Android, and iOS.

ReadRealm uses Jest for the NestJS backend, Flutter’s built-in test runner for the admin dashboard, Gradle for Android, and xcodebuild for iOS. This page covers how to run all of them.

Run all tests

To run the full test suite (backend + dashboard) in a single command:

task test

This runs task api:test followed by task dashboard:test.

Backend testing

The backend uses Jest configured in apps/api/package.json. Unit test files live in apps/api/src/ and match the pattern **/*.spec.ts. E2E tests are in apps/api/test/.

Unit tests

cd apps/api
npm run test

Or via the Taskfile:

task api:test

E2E tests

cd apps/api
npm run test:e2e

Or via the Taskfile:

task api:test:e2e
# (also available as: task test:e2e)

E2E tests run against a dedicated Jest config at apps/api/test/jest-e2e.json.

Coverage

cd apps/api
npm run test:cov

Coverage output is written to apps/api/coverage/. The Jest config collects coverage from all **/*.(t|j)s files under src/.

Watch mode

cd apps/api
npm run test:watch

Reruns affected tests automatically as files change. Useful during active development.

Aim for greater than 80% coverage on new backend code. Coverage reports are available in apps/api/coverage/ after running npm run test:cov.

Dashboard testing

The admin dashboard uses Flutter’s built-in test runner.

All tests

cd apps/dashboard
flutter test

Or via the Taskfile:

task dashboard:test

Single test file

cd apps/dashboard
flutter test test/path/to/test.dart

Coverage

cd apps/dashboard
flutter test --coverage

Coverage data is written to apps/dashboard/coverage/lcov.info.

Android testing

Android unit tests run via Gradle.

cd apps/android
./gradlew test

Or via the Taskfile:

task android:test

iOS testing

iOS tests run via xcodebuild.

cd apps/ios
xcodebuild test -workspace Runner.xcworkspace -scheme Runner

Or via the Taskfile:

task ios:test

Test structure overview

The NestJS backend co-locates spec files next to their source files, following NestJS conventions:

apps/api/src/
├── app.controller.spec.ts
├── auth/
│   ├── auth.controller.spec.ts
│   └── auth.service.spec.ts
├── book/
│   ├── book.controller.spec.ts
│   └── book.service.spec.ts
└── ...

apps/api/test/
└── jest-e2e.json          # E2E Jest configuration

Each module has spec files for both the controller and the service.

Tips for writing good tests

Backend (NestJS / Jest)

• Use @nestjs/testing to create isolated test modules with Test.createTestingModule().
• Mock external dependencies (MongoDB, third-party APIs) rather than calling them in unit tests.
• Use descriptive describe and it blocks so failures are easy to locate.
• Keep unit tests fast — reserve real database connections for E2E tests.
• Write at least one test for each controller endpoint and service method.

Dashboard (Flutter)

• Use Flutter’s testWidgets for widget tests and test for pure Dart unit tests.
• Use Provider overrides or mocks to isolate business logic from the widget under test.
• Use flutter test --coverage regularly to identify untested branches.
• Write widget tests for all new UI components.

Android (Kotlin / Gradle)

• Use JUnit 4 or JUnit 5 for unit tests.
• Mock API responses with a test double rather than hitting a live server.
• Test on API level 24 and above to match the supported range.

iOS (Swift / Xcode)

• Use XCTest for unit and UI tests.
• Test across different device sizes using Xcode simulators.
• Handle async operations with XCTestExpectation or Swift concurrency helpers.

Run task lint and task format before committing. Clean, consistently formatted code reduces noise in test output and code review.