Upgrading from 2.X to 3.X

[jackmatt2]

To upgrade you need to perform some mechanical refactoring of your code.

1. Previously you only needed a single dependency. This caused problems for people that wanted to use custom jackson plugins as the dependencies were shadowed. The Jackson JSON serializers have now been extracted to a separate dependency. You need to include that + jackson dependencies if you want to perform JSON serialization.

// In this case we are using the JUnit5 testing framework
testImplementation 'io.github.origin-energy:java-snapshot-testing-junit5:3.2.+'

// Many will want to serialize into JSON.  In this case you should also add the Jackson plugin
testImplementation 'io.github.origin-energy:java-snapshot-testing-plugin-jackson:3.2.+'
testImplementation 'com.fasterxml.jackson.core:jackson-core:2.11.3'
testImplementation 'com.fasterxml.jackson.core:jackson-databind:2.11.3'
testImplementation 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.11.3'
testImplementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.11.3'

// slf4j logging implementation if you don't already have one
testImplementation("org.slf4j:slf4j-simple:2.0.0-alpha0")

2. Create a snapshot.properties file in your resources folder with the following content

serializer=au.com.origin.snapshots.serializers.ToStringSnapshotSerializer
serializer.base64=au.com.origin.snapshots.serializers.Base64SnapshotSerializer
serializer.json=au.com.origin.snapshots.jackson.serializers.JacksonSnapshotSerializer
serializer.orderedJson=au.com.origin.snapshots.jackson.serializers.DeterministicJacksonSnapshotSerializer
comparator=au.com.origin.snapshots.comparators.PlainTextEqualsComparator
reporters=au.com.origin.snapshots.reporters.PlainTextSnapshotReporter
snapshot-dir=__snapshots__
output-dir=src/test/java
ci-env-var=CI

Above is your global configuration. Previously you needed to use an annotation to override the global defaults @UseSnapshotConfig . This is no longer necessary which prevents the need to constantly apply this annotation to each test class. You can most likely delete any @UseSnapshotConfig you had before although you can still use it in cases where you need it.

3. Define an instance variable private Expect expect; on each test class (Note that SnapshotMatcher.expect() no longer exists)

4. Refactor all your verifications from expect(YOUR_OBJECT).toMatchSnapshot() to this expect.toMatchSnapshot(YOUR_OBJECT)

5. If you were using .string(), .json() or .orderedJson() on your expect call, refactor to use their corresponding names from snapshot.properties.

.string() to .serializer("string") // assuming your define: serializer.string=au.com.origin.snapshots.serializers.ToStringSnapshotSerializer in snapshot.properties
.json() to .serializer("json")
.orderedJson() to  .serializer("orderedJson")

6. Run all tests. None of you existing snapshots should fail - the format has not changed.

7. Apply the new @SnapshotName("YOUR_CUSTOM_NAME") if desired (for spock tests it's required)

[dalbani]

Upgrading from 3.3.x to 3.5.x, I had to change the following in snapshot.properties:

serializer.json=au.com.origin.snapshots.jackson.serializers.JacksonSnapshotSerializer
serializer.orderedJson=au.com.origin.snapshots.jackson.serializers.DeterministicJacksonSnapshotSerializer

i.e. these classes are now under this jackson package.

[jackmatt2]

Yes - this was a breaking change as part of 3.4.0, I'll update the docs here too

https://github.com/origin-energy/java-snapshot-testing/releases/tag/3.4.0