UnitTesting

Unit Testing

Overview

CLARIN-DSpace v7 uses a two-tier test strategy managed by Maven:

• Unit tests — run by the Maven Surefire plugin (classes matching *Test.java).
• Integration tests — run by the Maven Failsafe plugin (classes matching *IT.java).

Both categories are skipped by default (skipUnitTests=true, skipIntegrationTests=true). You must explicitly enable them on the command line.

Key test dependencies

Dependency	Purpose
JUnit 4	Test framework
Mockito (inline)	Mocking
H2 Database	In-memory database for integration tests
Spring Boot Test	Application-context and MockMvc support
JaCoCo	Code-coverage reporting

Running tests

Running all unit tests

mvn install -DskipUnitTests=false

Running all integration tests

mvn install -DskipIntegrationTests=false

Running both unit and integration tests

mvn install -DskipUnitTests=false -DskipIntegrationTests=false

Running a single test class

# Unit test
mvn test -DskipUnitTests=false -Dtest=MyTest -pl dspace-api

# Integration test
mvn verify -DskipIntegrationTests=false -Dit.test=MyIT -pl dspace-server-webapp

The -pl <module> flag restricts execution to a single module, which speeds things up considerably.

Analyzing test reports

Reports are generated under each module's target/ directory:

• Unit tests: $MODULE/target/surefire-reports/
• Integration tests: $MODULE/target/failsafe-reports/

Code coverage

Activate JaCoCo coverage with the dedicated profiles:

# Unit-test coverage
mvn install -DskipUnitTests=false -P measure-unit-test-coverage

# Integration-test coverage
mvn install -DskipIntegrationTests=false -P measure-integration-test-coverage

Coverage reports are written to target/coverage-reports/.

Test base classes

The codebase provides several abstract base classes that handle boilerplate setup. Extend the one that matches your needs:

Base class	Module	Use when…
AbstractDSpaceTest	dspace-api	Pure unit test; initialises DSpace kernel and service manager
AbstractIntegrationTest	dspace-api	You need to manipulate runtime configuration during the test
AbstractIntegrationTestWithDatabase	dspace-api	You need an in-memory H2 database, a Context, and pre-created EPerson/admin objects
AbstractControllerIntegrationTest	dspace-server-webapp	REST API endpoint tests via MockMvc with full Spring Boot context
AbstractEntityIntegrationTest	dspace-server-webapp	Entity-specific REST API tests
AbstractWebClientIntegrationTest	dspace-server-webapp	Testing non-Spring servlets

Integration tests

Integration tests live alongside unit tests inside each module's src/test/ tree. They follow the Failsafe naming convention (*IT.java) and use an H2 in-memory database with a complete DSpace kernel.

Test environment

The testEnvironment.xml assembly descriptor builds a minimal DSpace installation directory (TestEnvironment.zip) that integration tests unpack at runtime. The dspace-api module installs this environment so that downstream modules can reuse it.

Key configuration files used during tests:

File	Location	Purpose
test-config.properties	src/test/resources/	Paths for test folders, bitstreams, CSV import/export
application-test.properties	dspace-server-webapp/src/test/resources/	Spring Boot overrides for tests
log4j2-test.xml	src/test/resources/	Logging configuration during test runs

Writing a new integration test

1. Create a class ending in IT (e.g., MyFeatureIT.java).
2. Extend AbstractIntegrationTestWithDatabase (API-level) or AbstractControllerIntegrationTest (REST-level).
3. Use the builder helpers to create test fixtures:

context.turnOffAuthorisationSystem();
Community community = CommunityBuilder.createCommunity(context).withName("Test").build();
Collection collection = CollectionBuilder.createCollection(context, community).build();
Item item = ItemBuilder.createItem(context, collection).withTitle("Sample").build();
context.restoreAuthSystemState();

CLARIN-specific tests

CLARIN extensions are covered by dedicated test classes. Examples:

Test class	Module	What it covers
ClarinTokenServiceTest	dspace-api	Token creation, deletion, encryption/decryption
MatomoReportSubscriptionServiceTest	dspace-api	Matomo analytics report subscriptions
ClarinLicenseResourceUserAllowanceDAOImplTest	dspace-api	License resource user-allowance DAO
BundleClarinTest	dspace-api	CLARIN-specific Bundle functionality

Frontend tests

The Angular frontend (dspace-angular) uses:

Tool	Purpose
Jasmine	Test framework
Karma	Test runner
Cypress	End-to-end tests
Istanbul	Coverage reporting

Running frontend tests

# Unit tests (single run)
npm test

# Unit tests in watch mode
npm run test:watch

# Headless (CI-friendly)
npm run test:headless

# Cypress E2E
npm run cypress:run        # headless
npm run cypress:open       # interactive

There are 20+ CLARIN-specific component test files (e.g., clarin-license-page.component.spec.ts, clarin-bitstream-download-page.component.spec.ts).