Skip to content

Commit

Permalink
Merge branch 'release/4.8.0.0'
Browse files Browse the repository at this point in the history
  • Loading branch information
@zambrovski
zambrovski committed Sep 22, 2023
2 parents 593c40a + 728aa44 commit 097376b
Show file tree
Hide file tree
Showing 91 changed files with 2,537 additions and 952 deletions.
6 changes: 3 additions & 3 deletions .github/release-notes.yml
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@


changelog:
sections:
- title: ":zap: Breaking Changes"
labels: [ "Type: breaking" ]
- title: ":rocket: Enhancements & Features"
labels: [ "Type: enhancement", "Type: documentation", "Type: example" ]
- title: ":bug: Bug Fixes"
Expand All @@ -13,4 +13,4 @@ changelog:
labels: [ "Type: question" ]
contributors:
exclude:
names: [ "dependabot[bot]" ]
names: [ "dependabot[bot]", "codacy-badger" ]
28 changes: 7 additions & 21 deletions .github/workflows/development.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,36 +5,22 @@ on: [ push ]
jobs:
build:
runs-on: ubuntu-latest
name: Build and run tests on JDK 11
name: Build and run tests
steps:
# Checkout the code
- name: Checkout code
uses: actions/checkout@v2
uses: actions/checkout@v3

- name: Expose branch name
run: echo ${{ github.ref }}

# Setup the cache
- name: Cache .m2
uses: actions/cache@v1
with:
path: ~/.m2/repository
key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
restore-keys: |
${{ runner.os }}-maven
# Get GPG private key into GPG
# - name: Import GPG Owner Trust
# run: echo ${{ secrets.GPG_OWNERTRUST }} | base64 --decode | gpg --import-ownertrust

# - name: Import GPG key
# run: echo ${{ secrets.GPG_SECRET_KEYS }} | base64 --decode | gpg --import --no-tty --batch --yes

# Setup JDK and Maven
- name: Set up JDK 11
uses: actions/setup-java@v1
uses: actions/setup-java@v3
with:
java-version: 11
java-version: 11.0.5
distribution: 'zulu'
cache: maven
server-id: ossrh
server-username: OSS_CENTRAL_USERNAME # env variable for Maven Central
server-password: OSS_CENTRAL_PASSWORD # env variable for Maven Central
Expand All @@ -45,7 +31,7 @@ jobs:

# Build
- name: Build with Maven
run: ./mvnw clean verify -U -B -T4
run: ./mvnw clean verify -U -B -T4 -ntp

# # Publish snapshot
# - name: Deploy a new snapshot to Maven Central
Expand Down
6 changes: 3 additions & 3 deletions .mvn/wrapper/maven-wrapper.properties
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
#
# http://www.apache.org/licenses/LICENSE-2.0
#
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.8.4/apache-maven-3.8.4-bin.zip
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.2/apache-maven-3.9.2-bin.zip
wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.1.0/maven-wrapper-3.1.0.jar
119 changes: 118 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,125 @@ For both kind of tests, we propose to use a JVM Framework for BDD testing called

### Axon Upcaster Testing

Writing event upcasters is sometimes difficult. Testing of them require even more effort. The library helps to create easy upcaster tests.
Writing event upcasters is sometimes difficult. Testing of them require even more effort. The library helps to create
easy upcaster JUnit 5 tests.

Imagine you need to test an upcaster for the `fixture.bankaccount.event.AccountCreatedEvent` in an application using
Jackson serializer. The old event revision was `12` and the new revision is `13`. There are only few steps needed to
implement such a test.

Please put the following dependency on your project classpath:

```xml
<dependency>
<groupId>io.holixon.axon.testing</groupId>
<artifactId>axon-testing-upcaster-junit5</artifactId>
<version>4.x.x.x</version>
<scope>test</scope>
</dependency>
```

Now create a JUnit 5 test for your upcaster:

```java
// the package is important to put event data in correct folder inside the test resources
package io.holixon.axon.testing.examples.upcaster.junit5.java;

// intentionally left out some trivial imports

import io.holixon.axon.testing.upcaster.MessageEncoding;
import io.holixon.axon.testing.upcaster.UpcasterTest;

import static io.holixon.axon.testing.upcaster.UpcasterTestSupport.*;

// the class name is important
public class AccountCreatedEventUpcastingJavaTest {

// must be defined as a static field of type matching the MessageEncoding
// the initialization is extracted to a separate method for simplicity
private final static JacksonSerializer jacksonSerializer = createJacksonSerializer();

// special annotation in use at least specifying the encoding type
@UpcasterTest(messageEncoding = MessageEncoding.JACKSON)
// important method name as the last folder
public void upcasts_account_created_jackson(
// will contain ordered sequence of source events, see explanation below
List<IntermediateEventRepresentation> sourceEvents,
// will contain ordered sequence of result events, see explanation below
List<IntermediateEventRepresentation> expectedSerializedEvents) {

AccountCreatedEventUpcaster upcaster = new AccountCreatedEventUpcaster();

Stream<IntermediateEventRepresentation> upcastedStream = upcaster.upcast(sourceEvents.stream());
List<AccountCreatedEvent> upcastedEvents = deserializeEvents(upcastedStream, jacksonSerializer).collect(
Collectors.toList());

// asserts
List<AccountCreatedEvent> expectedEvents = deserializeEvents(expectedSerializedEvents, jacksonSerializer);
assertThat(upcastedEvents).containExactlyElementsOf(expectedEvents);
}
}
```
This looks like a miracle that the source events are passed in to the test, can be directly passed to the upcaster under the test
and the result can be asserted using the collection of expected events. Indeed, the library makes use of JUnit 5 parameterized test
functionality, by defining a custom argument provider reading events from the file system.

We believe this is a good
practice for upcaster and upcaster chain testing, where several representations of different versions of the same event exist and must
be managed and set-up for the test. In also helps in situations where comparison with the expected event as an object in Java is
not feasible because only one version of a class may be available (probably the latest one).

Back to the test class implementation, please pay attention to the `static` `JacksonSerializer` defined in the test class and on
the full-qualified name of the test class and the test method name.

The content of the `src/test/resources` folder is as following:

```
└── io
└── holixon
└── axon
└── testing
└── examples
└── upcaster
└── junit5
└── java
└── AccountCreatedEventUpcastingJavaTest
└── upcasts_account_created_jackson
├── 1__fixture.bankaccount.event.AccountCreatedEvent__12.json
├── 2__fixture.bankaccount.event.AccountCreatedEvent__12.json
├── 1__fixture.bankaccount.event.AccountCreatedEvent__13__result.json
└── 2__fixture.bankaccount.event.AccountCreatedEvent__13__result.json
```

The full-qualified class name and the test method name are mapped to the directory structure. Inside the test data directory,
there are four files. Those two of them without the `__result` suffix are read in and considered to be JSON representations
of source events. The source events are passed to the test method annotated by the `@UpcasterTest` as a first parameter `sourceEvents`.
The other two with the `__result` suffix are considered to be JSON representations of the expected events, received after the
upcaster run. Those will be passed to the test method as the second parameter `expectedSerializedEvents`.

The ordering of the files (in each group) is determined based on the first numbers before the first `__` separator. The next part of
the file name is considered as the type name of the stored event. Finally, the last number is representing the revision of the event.

You may want to use only parts of the functionality above. A good starting point for this are our examples. Please consider to look at the
`io.holixon.axon.testing.upcaster.UpcasterTestSupport` class for helpful methods. In addition, you might want to use the `@UpcasterTest`
functionality in a slightly different way. The method signature of the test method may have one or two parameters (expected events must not be read
from the filesystem) of different types: `List<IntermediateEventRepresentation>` to get intermediate representation, `List<String>` to get
the file content of the read-in files or just `List<File>` to get the files matching criteria. There are some additional options on
the `@UpcasterTest` annotation to tune the behaviour of the parameterized test argument provider. You can specify different strategy to
resolve the payload type and revision and a different content retrieval strategy.

## Changelog

* Beginning with release `4.7.4.0` we changed to a semantic versioning model where the first 3 digits refer to the axon framework version this lib is supposed to work withm the last digit is the build version of this lib against the framework.


## License

This library is developed under

[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](/LICENSE)

## Sponsors and Customers

[![sponsored](https://img.shields.io/badge/sponsoredBy-Holisticon-red.svg)](https://holisticon.de/)

66 changes: 0 additions & 66 deletions examples/bankaccount-jgiven-junit4/pom.xml
View file
Original file line number Diff line number Diff line change
@@ -1,66 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>io.holixon.axon.testing._</groupId>
<artifactId>examples</artifactId>
<version>4.7.4.0</version>
</parent>

<groupId>io.holixon.axon.testing.examples</groupId>
<artifactId>bankaccount-jgiven-junit4</artifactId>

<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.holixon.axon.testing</groupId>
<artifactId>axon-testing-jgiven-junit</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.toolisticon.testing</groupId>
<artifactId>jgiven-kotlin</artifactId>
<version>1.2.5.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.holixon.axon.testing.lib</groupId>
<artifactId>axon-testing-fixtures-bankaccount</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>2.0.7</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
<version>3.24.2</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
<version>5.3.1</version>
<scope>test</scope>
</dependency>
</dependencies>

<!-- <build>-->
<!-- <plugins>-->
<!-- <plugin>-->
<!-- <groupId>org.apache.maven.plugins</groupId>-->
<!-- <artifactId>maven-compiler-plugin</artifactId>-->
<!-- </plugin>-->
<!-- </plugins>-->
<!-- </build>-->
</project>
Loading

0 comments on commit 097376b

Please sign in to comment.