Skip to main content

Test Framework

Experimental

The test framework is an experimental feature. Its expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact., annotations and APIs can still change in future versions.

The test framework expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. let you test the back-end of an NS applicationNS Application (NSApplication). A pre-built software stack that provides common enterprise application functionality such as CRUD, search, authentication, and business process modeling out of the box. with plain JUnit tests, without deploying the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution..

The framework simulates JNDI lookups and EJB injection, so agents and beans work as they do on the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. server. It also provides an H2 in-memory database that uses the SQL dialect of your applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution.. FindersFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement., query searchesQuery Search (QuerySearch). An advanced search mechanism using declarative constraints to build complex, multi-variable or cross-component queries. and custom queries therefore run as they do in production.

With the framework you can:

  • Test the logic layerLayerLogical separation of functionality within a single system/application, focused on code organization., data layerLayerLogical separation of functionality within a single system/application, focused on code organization. and database queries together.
  • Replace any bean with a mock, to test one class in isolation or to force a specific result.
Existing test suites

The test framework does not replace your existing test suites that use operators. Keep those tests as they are, and use the test framework to extend the suite with new tests. You only need to convert an operator test if you want to. See Extending operator test suites.

tip

Not sure if the test framework is the right tool for your test? See Choosing a test type.

Quick start​

1. Check the requirements​

  • The persistence provider of your application instanceApplication Instance (ApplicationInstance). A target technology configuration defining how an application's architecture layers are built and executed. is Hibernate. For another provider, see Using another persistence provider.
  • The target database of your application instanceApplication Instance (ApplicationInstance). A target technology configuration defining how an application's architecture layers are built and executed. is PostgreSQL, SQL Server, Oracle, DB2, MySQL, MariaDB or HSQLDB.
  • Your tests use JUnit 5 or later (JUnit Jupiter, org.junit.jupiter.api). The framework does not work with JUnit 4.

2. Add the expansion resources​

Add the expansion resourcesExpansion Resource (ExpansionResource). A reusable resource bundle containing expanders and features that provide specific application capabilities, defined in the expansion settings and added to the classpath during expansion. below to your applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. and expand it.

  1. Navigate to Settings > expansionResources.
  2. Add the following expansion resources, each with version 1.0.3:
    • net.democritus.test:test-framework-jee-core-expanders
    • net.democritus.test:test-framework-data-layer-jee-expanders
    • net.democritus.test:test-framework-logic-layer-jee-expanders

The expansion adds a test-framework module to the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. and to each component. See Project structure for what each module contains.

3. Write a test​

Add a test class to <component>/test-framework/test/common/src of the component you want to test. Annotate the class with @WithTestFramework (utils.annotation.WithTestFramework).

The example below creates a Car through its local agent. It runs the real logic layerLayerLogical separation of functionality within a single system/application, focused on code organization., data layerLayerLogical separation of functionality within a single system/application, focused on code organization. and in-memory database.

CreateCarTest.java
@WithTestFramework
public class CreateCarTest {

@Test
public void testCreateCar() {
CarLocalAgent carAgent = CarLocalAgent.getCarAgent(Context.emptyContext());

CarDetails details = new CarDetails();
details.setName("Car 1");
details.setBrand("Mercedes");
details.setModel("CLA");
details.setNumberplate("1-ABC-123");

CrudsResult<DataRef> createResult = carAgent.create(details);
assertTrue(createResult.isSuccess());
}
}

4. Run the test​

Run the test from your IDE, for example IntelliJ, like any other unit test. To run all tests from the command line, use the default Maven command:

mvn test

How the framework works​

The @WithTestFramework annotation sets up the following for every test class:

  • EJB fieldsFieldA property of a DataElement expanded to a database column and user interface input element.: every EJB fieldFieldA property of a DataElement expanded to a database column and user interface input element. is initialised. You can replace any bean with a mock, see Mocking beans.
  • Agents: every local agent is available through <DataElement>LocalAgent.get<DataElement>Agent(context). This includes the agents of component dependencies, such as account.
  • Events: data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. events are replaced by mocks that only log the event.
  • Database: the in-memory database starts the first time a test reaches the database. Tests that never reach it therefore run a lot faster.
  • Transactions: each test runs in its own transaction, which is rolled back after the test. Data created in one test is not visible in the next one.

Project structure​

FolderContentsEdit?
<component>/test-framework/test/common/srcYour test classes.Yes
<component>/test-framework/ext/common/srcYour shared test helpers, such as test data factories.Yes
<component>/test-framework/genBean registrations, local test agents and event mocks of the component.Custom anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion. only
<component>/test-framework/gen_testThe @WithTestFramework annotation and its JUnit extensions.Custom anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion. only
<application>/test-framework/genShared framework code, the persistence.xml, the database scripts and the logging configuration.Custom anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion. only

Writing tests​

Test data factories​

Most tests need data elementsData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. that pass all validations. Put reusable test data in factory classes in <component>/test-framework/ext/common/src. This keeps your tests short and gives you one place to update when validations change.

CarFactory.java
public class CarFactory {
private final CarDetails carDetails;

private CarFactory(CarDetails carDetails) {
this.carDetails = carDetails;
}

public static CarFactory mercedesCla() {
CarDetails carDetails = new CarDetails();
carDetails.setName("Mercedes CLA");
carDetails.setBrand("Mercedes");
carDetails.setModel("CLA");
carDetails.setNumberplate("1-ABC-123");
return new CarFactory(carDetails);
}

public static CarFactory volkswagenGolf() {
CarDetails carDetails = new CarDetails();
carDetails.setName("Volkswagen Golf");
carDetails.setBrand("Volkswagen");
carDetails.setModel("Golf");
carDetails.setNumberplate("2-DEF-456");
return new CarFactory(carDetails);
}

public CarDetails getDetails() {
return carDetails;
}

public DataRef create(Context context) {
CrudsResult<DataRef> createResult = CarLocalAgent.getCarAgent(context).create(carDetails);
assertTrue(createResult.isSuccess());
return createResult.getValue();
}

public CarDetails createAndGetDetails(Context context) {
CarLocalAgent carAgent = CarLocalAgent.getCarAgent(context);
CrudsResult<CarDetails> getDetailsResult = carAgent.getDetails(create(context));
assertTrue(getDetailsResult.isSuccess());
return getDetailsResult.getValue();
}
}

Testing finders and query searches​

Create the data your test needs, then call the finderFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement. or query searchQuery Search (QuerySearch). An advanced search mechanism using declarative constraints to build complex, multi-variable or cross-component queries. through the local agent. The example checks that the finderFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement. findByBrandEq only returns cars of the given brand.

CarFinderTest.java
@WithTestFramework
public class CarFinderTest {

@Test
public void testFindByBrandEq() {
Context context = Context.emptyContext();
CarDetails mercedes = mercedesCla().createAndGetDetails(context);
volkswagenGolf().create(context);

CarFindByBrandEqDetails finderDetails = new CarFindByBrandEqDetails();
finderDetails.setBrand("Mercedes");

CarLocalAgent carAgent = CarLocalAgent.getCarAgent(context);
SearchResult<CarDetails> searchResult = carAgent.find(SearchDetails.fetchAllDetails(finderDetails));

assertTrue(searchResult.isSuccess());
assertEquals(1, searchResult.getTotalNumberOfItems());
assertEquals(mercedes.getId(), searchResult.getFirstResult().get().getId());
}
}

Testing validations​

Validations run as they do on the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. server. To test an unhappy flow, create invalid data and check the diagnostic. The example assumes the fieldFieldA property of a DataElement expanded to a database column and user interface input element. name of Car has the option isRequired.

@Test
public void testCreateCarWithoutName() {
CarDetails carDetails = mercedesCla().getDetails();
carDetails.setName(null);

CrudsResult<DataRef> createResult = CarLocalAgent.getCarAgent(Context.emptyContext()).create(carDetails);

assertTrue(createResult.isError());
assertEquals("carRental.car.name.required", createResult.getDiagnostics().get(0).getKey());
}

Mocking beans​

Most EJB fieldsFieldA property of a DataElement expanded to a database column and user interface input element. are initialised automatically. Register a bean yourself when you want to:

  • Mock a bean: replace a bean, or some of its methods, with a mock.
  • Bind an interface: use a specific implementation for an interface.
  • Initialise a bean: run extra setup after the bean is constructed.

Registrations are stored in TestBeanRegistry (test.framework.utils.TestBeanRegistry), which has two registries:

RegistryScopeWhere to register
TestBeanRegistry.LOCAL_REGISTRYOne test class. Reset before and after each test class.In the test class, usually in a @BeforeAll method.
TestBeanRegistry.GLOBAL_REGISTRYAll test classes that use the framework.In the custom anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion. of <Component>EjbFieldTypeRegistration.

When a bean is requested, the framework looks in the local registry first and then in the global registry. Each bean is created once per registry and reused afterwards.

Both registries offer the same methods:

MethodUse
registerImplementation(Interface.class, Implementation.class)Bind an interface to an implementation class, such as a mock that implements the interface.
register(Type.class, supplier)Create the bean with your own supplier, for example a mock constructor or a lambda.
registerInstance(Type.class, instance)Use an instance you created yourself.

Mocking in one test class​

Use the local registry when a mock is only needed in one test class. In the example below, the query searchQuery Search (QuerySearch). An advanced search mechanism using declarative constraints to build complex, multi-variable or cross-component queries. of Car returns an error. All other methods of CarBean keep their real behaviour.

@WithTestFramework
public class CarQuerySearchErrorTest {

@BeforeAll
public static void setup() {
class QuerySearchMock extends CarBean {
@Override
public <S extends CarElementQueryFilter, T> SearchResult<T> querySearch(ParameterContext<SearchDetails<S>> searchParameter) {
return SearchResult.error(Diagnostic.error("carRental", "Car", "querysearch.failed"));
}
}
TestBeanRegistry.LOCAL_REGISTRY.registerImplementation(CarLocal.class, QuerySearchMock.class);
}

@Test
public void testQuerySearchError() {
CarLocalAgent carAgent = CarLocalAgent.getCarAgent(Context.emptyContext());

SearchResult<CarDetails> searchResult = carAgent.querySearch(SearchDetails.fetchAllDetails(new CarQueryFilter()));

assertTrue(searchResult.isError());
assertEquals("querysearch.failed", searchResult.getDiagnostics().get(0).getKey());
}
}

You can also register in a test method. The registration then applies from that point on, until the end of the test class.

Mocking in all test classes​

Use the global registry when every test needs the same registration. The global registry is built once, before any test starts, by the JUnit extension Register<Component>EjbFieldTypesExtension. Add your registrations to the custom anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion. of <component>/test-framework/gen/common/src/utils/<Component>EjbFieldTypeRegistration.java.

The example shows each type of registration. Use only the one you need: a later registration for the same class overrides an earlier one.

// anchor:custom-register-ejb-field-types:start
// Bind an interface to the implementation that has to be used
GLOBAL_REGISTRY.registerImplementation(CarLocal.class, CarBean.class);

// Register a mock. You can do this in two ways:
// 1. Bind the interface to the mock (CarBeanMock has to implement CarLocal)
GLOBAL_REGISTRY.registerImplementation(CarLocal.class, CarBeanMock.class);
// 2. Register a supplier for the bean (CarBeanMock has to extend CarBean)
GLOBAL_REGISTRY.register(CarBean.class, CarBeanMock::new);

// Register a custom initialisation of the bean
GLOBAL_REGISTRY.register(CarBean.class, () -> {
CarBean carBean = new CarBean();
carBean.doSomething();
return carBean;
});
// anchor:custom-register-ejb-field-types:end

In-memory database​

The framework uses an H2 in-memory database in the compatibility mode of your applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution.'s target database. Write custom SQL in that dialect. The tables are created automatically from the JPA annotations on the data classes, with a schema for each component.

All files below are in <application>/test-framework/gen/jpa/resources. Add your changes to their custom anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion..

FileCustom anchorAnchorA marker within generated source code reserved for adding custom logic during re-expansion.Use
META-INF/persistence.xmlcustom-entitiesAdd custom JPA data classes.
META-INF/persistence.xmlcustom-additional-propertiesAdd or override persistence properties.
META-INF/persistence.xmlprovider, properties (feature anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion.)Add another persistence provider. See Using another persistence provider.
test-database/initialise-database.sqlcustom-init-databaseRun SQL before the tables are created, for example to create a sequence.
test-database/import-initial-data.sqlcustom-init-databaseInsert data after the tables are created. This data is available in all tests.

Using another persistence provider​

The framework sets the persistence provider only when your application instanceApplication Instance (ApplicationInstance). A target technology configuration defining how an application's architecture layers are built and executed. uses Hibernate. For another provider, persistence.xml has two feature anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion. that an expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. can fill:

  • provider: the <provider> element of the persistence unit.
  • properties: the provider-specific properties, inside the <properties> element.

See Features for how to fill feature anchorsAnchorA marker within generated source code reserved for adding custom logic during re-expansion. with an expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. feature.

Initialising the database​

For example, to create a sequence in initialise-database.sql:

-- anchor:custom-init-database:start
CREATE SEQUENCE IF NOT EXISTS CARRENTAL.CAR_NUMBER_SEQ START WITH 100 INCREMENT BY 1;
-- anchor:custom-init-database:end

Importing initial test data​

Use import-initial-data.sql for data that almost every test needs, such as users and accounts. For data that only some tests need, use test data factories instead.

The example inserts an admin user for an applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. with a PostgreSQL target database:

-- anchor:custom-init-database:start
INSERT INTO ACCOUNT."User" (account_id, disabled, email, encryptedPassword, enteredAt, firstName, fullName, language, lastModifiedAt, lastName, mobile, name, password, persNr, profile_id, timeout) VALUES
((SELECT id FROM ACCOUNT.Account WHERE name = 'NSX'), 'no', 'admin@example.com', '', current_date, '', 'Administrator', 'english',
current_date, '', '', 'admin', '', '', (SELECT id FROM ACCOUNT.Profile WHERE name = 'admin'), 3600);
-- anchor:custom-init-database:end

Logging​

The framework uses logback-classic for logging. The default configuration is in <application>/test-framework/gen/common/resources/logback.xml and logs at level INFO. To override it, add a logback-test.xml file to the test resources folder. Logback loads logback-test.xml before logback.xml.