Skip to content

Commit f5022f8

Browse files
SplatcrafterSplatcrafter
authored
Merge pull request #8 from aether-framework/feature/testkit-module
Update README and add Testkit module documentation
2 parents 0400496 + 10aede4 commit f5022f8

33 files changed

Lines changed: 8766 additions & 216 deletions

‎README.md‎

Lines changed: 93 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,14 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
1010

1111
---
1212

13-
## ✨ Features (v0.1.0)
13+
## ✨ Features (v0.2.0)
1414

1515
- ✅ **Schema-Based Versioning** — Define data types per version with `Schema` and `TypeRegistry`
1616
- ✅ **Forward Patching** — Apply `DataFix` instances sequentially to migrate data across versions
1717
- ✅ **Format-Agnostic** — Work with any serialization format via `Dynamic<T>` and `DynamicOps<T>`
1818
- ✅ **Codec System** — Bidirectional transformation between typed Java objects and dynamic representations
1919
- ✅ **Type Safety** — Strong typing with `TypeReference` identifiers for data routing
20+
- ✅ **Testkit** — Fluent test data builders, custom assertions, and test harnesses for DataFix testing
2021
- ✅ **JDK 17+** — Built and tested on modern LTS JVMs
2122

2223
---
@@ -26,6 +27,7 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
2627
- **aether-datafixers-api** — Core interfaces and API contracts (no implementation logic)
2728
- **aether-datafixers-core** — Default implementations of the API interfaces
2829
- **aether-datafixers-codec** — Codec implementations for serialization formats
30+
- **aether-datafixers-testkit** — Testing utilities for DataFix, Schema, and migration testing
2931
- **aether-datafixers-examples** — Practical examples demonstrating real-world usage
3032
- **aether-datafixers-bom** — Bill of Materials for coordinated dependency management
3133

@@ -282,6 +284,66 @@ public class MyFix extends SchemaDataFix {
282284

283285
---
284286

287+
## 🧪 Testing with Testkit
288+
289+
The `aether-datafixers-testkit` module provides utilities for testing your migrations:
290+
291+
```java
292+
import de.splatgames.aether.datafixers.testkit.TestData;
293+
import de.splatgames.aether.datafixers.testkit.factory.QuickFix;
294+
import de.splatgames.aether.datafixers.testkit.harness.DataFixTester;
295+
import static de.splatgames.aether.datafixers.testkit.assertion.AetherAssertions.assertThat;
296+
297+
@Test
298+
void testFieldRename() {
299+
// Create a quick fix for testing
300+
var fix = QuickFix.renameField(
301+
GsonOps.INSTANCE, "rename_player_name", 1, 2,
302+
"playerName", "name"
303+
);
304+
305+
// Create test data fluently
306+
Dynamic<JsonElement> input = TestData.gson().object()
307+
.put("playerName", "Alice")
308+
.put("level", 10)
309+
.build();
310+
311+
// Apply and verify
312+
Dynamic<JsonElement> result = DataFixTester.forFix(fix)
313+
.withInput(input)
314+
.forType("player")
315+
.apply();
316+
317+
// Use custom assertions
318+
assertThat(result)
319+
.hasStringField("name", "Alice")
320+
.hasIntField("level", 10)
321+
.doesNotHaveField("playerName");
322+
}
323+
```
324+
325+
### Testkit Features
326+
327+
| Component | Description |
328+
|-----------|-------------|
329+
| **TestData** | Fluent builders for creating test data (`TestData.gson().object()...`) |
330+
| **AetherAssertions** | Custom AssertJ assertions for `Dynamic`, `DataResult`, `Typed` |
331+
| **DataFixTester** | Test harness for isolated DataFix testing |
332+
| **QuickFix** | Factory methods for common fix patterns (rename, add, remove, transform) |
333+
| **MockSchemas** | Mock schema utilities for testing |
334+
335+
Add to your project:
336+
337+
```xml
338+
<dependency>
339+
<groupId>de.splatgames.aether.datafixers</groupId>
340+
<artifactId>aether-datafixers-testkit</artifactId>
341+
<scope>test</scope>
342+
</dependency>
343+
```
344+
345+
---
346+
285347
## 📖 Examples
286348

287349
The `aether-datafixers-examples` module provides a complete, runnable example demonstrating real-world usage patterns.
@@ -339,21 +401,38 @@ mvn test
339401
## 🗺️ Roadmap
340402

341403
- **v0.1.0** (current)
342-
- Core API and default implementations
343-
- Schema-based versioning with TypeRegistry
344-
- DataFix forward patching system
345-
- Dynamic/DynamicOps format abstraction
346-
- Basic codec infrastructure
347-
348-
- **v0.2.0**
349-
- Additional codec implementations
350-
- Extended type rewrite rules
351-
- Performance optimizations
404+
- Core API and default implementations
405+
- Schema-based versioning with TypeRegistry
406+
- DataFix forward patching system
407+
- Dynamic/DynamicOps format abstraction
408+
- Basic codec infrastructure
409+
410+
- **v0.2.0** (next)
411+
- **Testkit module** — Fluent test data builders, custom AssertJ assertions, test harnesses
412+
- **Migration diagnostics** — Optional structured report (applied fixes, touched types, timing)
413+
- **Policy system** — Configurable handling for warnings/logs/unknown fields/types during migration
414+
- **Codec improvements** — Better error reporting, parity improvements for GsonOps/JacksonOps
415+
- **Extended rewrite rules** — Common operations like nested rename/move/copy helpers
416+
- Performance optimizations
417+
418+
- **v0.3.0**
419+
- **CLI module** — Migrate files and print/export a migration report (batch-friendly)
420+
- **Schema tooling** — Runtime schema validation + diff utilities between versions
421+
422+
- **v0.4.0**
423+
- **Extra ops modules** — Optional YAML/TOML support (format adapters)
424+
- **Debug utilities** — Pretty printers / tree diff for Dynamic structures (dev-facing)
425+
426+
- **v0.5.0** (API freeze candidate)
427+
- **API stabilization pass** — Naming/packaging cleanup + deprecations completed
428+
- **Compatibility checks in CI** — Binary/source compatibility guardrails for public API
429+
- **Hardened error model** — Consistent exception types + structured error details
430+
- **Release readiness** — Final review of docs/examples against frozen API
352431

353432
- **v1.0.0**
354-
- Stable API surface
355-
- Comprehensive documentation
356-
- Production-ready release
433+
- Stable API surface
434+
- Comprehensive documentation
435+
- Production-ready release
357436

358437
---
359438

‎aether-datafixers-bom/pom.xml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,11 @@
3232
<artifactId>aether-datafixers-codec</artifactId>
3333
<version>${project.version}</version>
3434
</dependency>
35+
<dependency>
36+
<groupId>de.splatgames.aether.datafixers</groupId>
37+
<artifactId>aether-datafixers-testkit</artifactId>
38+
<version>${project.version}</version>
39+
</dependency>
3540
</dependencies>
3641
</dependencyManagement>
3742
</project>

‎aether-datafixers-testkit/pom.xml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
<parent>
7+
<groupId>de.splatgames.aether.datafixers</groupId>
8+
<artifactId>aether-datafixers</artifactId>
9+
<version>0.2.0-SNAPSHOT</version>
10+
</parent>
11+
12+
<artifactId>aether-datafixers-testkit</artifactId>
13+
<packaging>jar</packaging>
14+
15+
<name>Aether Datafixers :: Testkit</name>
16+
<description>Testing utilities for Aether Datafixers - fluent builders, custom assertions, and test harnesses for DataFix, Schema, and migration testing.</description>
17+
18+
<dependencies>
19+
<!-- Framework dependencies -->
20+
<dependency>
21+
<groupId>de.splatgames.aether.datafixers</groupId>
22+
<artifactId>aether-datafixers-api</artifactId>
23+
</dependency>
24+
<dependency>
25+
<groupId>de.splatgames.aether.datafixers</groupId>
26+
<artifactId>aether-datafixers-core</artifactId>
27+
</dependency>
28+
<dependency>
29+
<groupId>de.splatgames.aether.datafixers</groupId>
30+
<artifactId>aether-datafixers-codec</artifactId>
31+
</dependency>
32+
33+
<!-- JetBrains annotations -->
34+
<dependency>
35+
<groupId>org.jetbrains</groupId>
36+
<artifactId>annotations</artifactId>
37+
</dependency>
38+
39+
<!-- Guava for Preconditions and utilities -->
40+
<dependency>
41+
<groupId>com.google.guava</groupId>
42+
<artifactId>guava</artifactId>
43+
</dependency>
44+
45+
<!-- Gson for TestData.gson() -->
46+
<dependency>
47+
<groupId>com.google.code.gson</groupId>
48+
<artifactId>gson</artifactId>
49+
</dependency>
50+
51+
<!-- Jackson for TestData.jackson() -->
52+
<dependency>
53+
<groupId>com.fasterxml.jackson.core</groupId>
54+
<artifactId>jackson-databind</artifactId>
55+
</dependency>
56+
57+
<!-- Testing dependencies (compile scope - this IS a test library!) -->
58+
<dependency>
59+
<groupId>org.junit.jupiter</groupId>
60+
<artifactId>junit-jupiter</artifactId>
61+
<scope>compile</scope>
62+
</dependency>
63+
<dependency>
64+
<groupId>org.assertj</groupId>
65+
<artifactId>assertj-core</artifactId>
66+
<scope>compile</scope>
67+
</dependency>
68+
</dependencies>
69+
70+
<build>
71+
<plugins>
72+
<plugin>
73+
<groupId>org.apache.maven.plugins</groupId>
74+
<artifactId>maven-compiler-plugin</artifactId>
75+
</plugin>
76+
<plugin>
77+
<groupId>org.apache.maven.plugins</groupId>
78+
<artifactId>maven-surefire-plugin</artifactId>
79+
</plugin>
80+
</plugins>
81+
</build>
82+
</project>

0 commit comments

Comments
 (0)