Context Mapper ArchUnit Extension
This library can help you validating your code against a Context Mapper DSL (CML) model. It enables Context Mapper users to ensure that the implemented code (tactic DDD) corresponds to the CML model with ArchUnit. To make this work, you need to annotate your Java classes with the tactic DDD concepts. Our library supports jMolecules out of the box; but you can use your own set of annotations as well.
Usage
You can use this library to write ArchUnit tests by including it into your Gradle or Maven project.
Gradle:
testImplementation 'org.contextmapper:context-mapper-archunit-extension:1.2.0'
Maven:
<dependency>
<groupId>org.contextmapper</groupId>
<artifactId>context-mapper-archunit-extension</artifactId>
<version>1.2.0</version>
</dependency>
JavaDoc
Besides the code example below, you can find the complete JavaDoc of the libraries API here.
Use all our test cases
The simplest way to apply all our test predefined test cases is to extend our AbstractTacticArchUnitTest
. An example:
class TacticArchUnitTestExample extends AbstractTacticArchUnitTest {
@Override
protected String getBoundedContextName() {
return "SampleContext";
}
@Override
protected String getCMLFilePath() {
return "src/test/cml/test.cml";
}
@Override
protected String getJavaPackageName2Test() {
return "org.contextmapper.archunit.sample.sampleaggregate1";
}
}
You basically have to provide three parameters:
- The name of the Bounded Context against you want to test (CML).
- The path to the CML file.
- The package that shall be scanned for the JMolecules annotations.
Implement custom set of rules
In case you don't want apply all our rules, you can also implement your custom test cases. An example:
public class ExampleArchitectureTest {
private BoundedContext context;
private JavaClasses classes;
@BeforeEach
protected void setup() {
this.context = new BoundedContextResolver()
.resolveBoundedContextFromModel("src/main/cml/model.cml", "SampleBoundedContext");
this.classes = new ClassFileImporter()
.withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
.importPackages("org.example.app");
}
@Test
void aggregatesShouldBeModeledInCML() {
aggregateClassesShouldBeModeledInCml(context).check(classes);
}
@Test
void entitiesShouldBeModeledInCML() {
entityClassesShouldBeModeledInCml(context).check(classes);
}
@Test
void valueObjectsShouldBeModeledInCML() {
valueObjectClassesShouldBeModeledInCml(context).check(classes);
}
}
The three example tests above ensure that Aggregates, Entities, and Value Objects that exist in the Java code, also exist in the CML model. In case a developer adds an Aggregate, Entity, or Value Object to the code that is not part of the CML model, the test will fail.
The example above uses our predefined rules based on the jMolecules annotations. You can find all available rules here. The next section shows how you can write your own rules, in case you don't want to use jMolecules.
Use custom annotations
By using only our ArchCondition's it is also possible to implement the tests with other annotations than JMolecules:
public class ExampleArchitectureTest {
protected BoundedContext context;
protected JavaClasses classes;
@BeforeEach
protected void setup() {
this.context = new BoundedContextResolver()
.resolveBoundedContextFromModel("src/main/cml/model.cml", "SampleBoundedContext");
this.classes = new ClassFileImporter()
.withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
.importPackages("org.example.app");
}
@Test
void aggregatesShouldBeModeledInCML() {
classes().that().areAnnotatedWith(Aggregate.class).should(beModeledAsAggregatesInCML(context));
}
@Test
void entitiesShouldBeModeledInCML() {
classes().that().areAnnotatedWith(Entity.class).should(beModeledAsEntitiesInCML(context));
}
@Test
void valueObjectsShouldBeModeledInCML() {
classes().that().areAnnotatedWith(ValueObject.class).should(beModeledAsValueObjectsInCML(context));
}
}
As the example illustrates, in this case you are able to select your classes with your own code (using your own annotations); but you can still use our conditions, that check specific things in the CML model. You can find all conditions that are currently available here.
Available Rules and Conditions
Hint: The available rules are implemented with the jMolecules DDD annotations. However, you can implement the same rules with your own set of annotations or interfaces by using the corresponding ArchUnit conditions (as documented above).
Rule / Condition | Description |
---|---|
aggregatesShouldBeModeledInCML |
Aggregates that are implemented in the code (for example annotated with @AggregateRoot jMolecules annotation) shall exist in the CML Bounded Context as well. |
modulesShouldBeModeledInCML |
Modules that are implemented in the code (for example annotated with @Module jMolecules annotation) shall exist in the CML Bounded Context as well. |
entitiesShouldBeModeledInCML |
Entities that are implemented in the code (for example annotated with @Entity jMolecules annotation) shall exist in the CML Bounded Context as well. |
valueObjectsShouldBeModeledInCML |
Value Objects that are implemented in the code (for example annotated with @ValueObject jMolecules annotation) shall exist in the CML Bounded Context as well. |
domainEventsShouldBeModeledInCML |
Domain events that are implemented in the code (for example annotated with @DomainEvent jMolecules annotation) shall exist int the CML Bounded Context as well. |
servicesShouldBeModeledInCML |
Services that are implemented in the code (for example annotated with @Service jMolecules annotation) shall exist in the CML Bounded Context as well. |
repositoriesShouldBeModeledInCML |
Repositories that are implemented in the code (for example annotated with @Repository annotation) shall exist in the CML Bounded Context as well. |
aggregatesShouldAdhereToCmlAggregateStructure |
This rule ensures that an Aggregate in the code (basically a Java package with a marker on the aggregate root entity; for example annotated with @AggregateRoot jMolecules annotation) consists of the same entities, value objects, and domain events as it is modeled in CML. |
entitiesShouldAdhereToCmlEntityStructure |
This rule ensures that the fields of an entity in the code (for example annotated with @Entity jMolecules annotation) are also modeled in the corresponding CML entity. |
valueObjectsShouldAdhereToCmlValueObjectStructure |
This rule ensures that the fields of a value object in the code (for example annotated with @ValueObject jMolecules annotation) are also modeled in the corresponding CML value object. |
domainEventsShouldAdhereToCmlDomainEventStructure |
This rule ensures that the fields of a domain event in the code (for example annotated with @DomainEvent jMolecules annotation) are also modeled in the corresponding CML domain event. |
The rules and conditions are documented in our JavaDoc as well.
Missing some rules/conditions? Contributions are always welcome! Create PRs or GitHub issues with your ideas/requirements.
Contributing
Contribution is always welcome! Here are some ways how you can contribute:
- Create Github issues if you find bugs or just want to give suggestions for improvements.
- This is an open source project: if you want to code, create pull requests from forks of this repository. Please refer to a Github issue if you contribute this way.
- If you want to contribute to our documentation and user guides on our website https://contextmapper.org/, create pull requests from forks of the corresponding page repo https://github.com/ContextMapper/contextmapper.github.io or create issues there.
Licence
ContextMapper is released under the Apache License, Version 2.0.