feat(archetype): Add example ITs for the nine new core audits

jeffjensen · jeffjensen · commit 4f4f24253218 · 2026-07-07T21:20:35.000-05:00
One <Audit>AuditIT template per new audit, under its family directory (catalog/jpa/runtime), following the existing pattern: extends AbstractDatabaseAuditIT (or the user's parentClass), @Autowired the assertion bean, and demonstrate the exclusion constant. UnusedIndexAuditIT is plan-based (PostgreSQL-only), so it joins Join/OrderBy/WhereClause in archetype-post-generate.groovy's deletion list for non-PostgreSQL engines. Fixing the demo schema to pass all three new catalog/JPA audits cleanly surfaced two real gaps: * Liquibase's own bookkeeping tables (databasechangelog, databasechangeloglock) are unmapped by design, and databasechangeloglock's PK is a narrow INT - both genuine findings PrimaryKeyTypeAuditIT and UnmappedDatabaseObjectAuditIT now exclude, the same way PrimaryKeyPresenceAuditAssertion already special-cases them for the presence audit. * The demo's Parent/Child entities had no @Version attribute. Rather than excluding them, added a genuine version column (Liquibase + entity + getter) to both, since a versioned entity is worth demonstrating rather than suppressing - Spring Data's save() handles it transparently, so RepositoryWorkloadIT needed no change. Full reactor `clean install` (which drives archetype:integration-test against Testcontainers PostgreSQL/MySQL) is green: 20/20 in the full and targeted-datasource projects, 16/16 in full-mysql.
diff --git a/archetype/src/main/resources/META-INF/archetype-post-generate.groovy b/archetype/src/main/resources/META-INF/archetype-post-generate.groovy
@@ -64,14 +64,16 @@ if (parentClass != 'none') {
     new File(destRoot, "src/test/java/${packagePath}/AbstractDatabaseAuditIT.java").delete()
 }
 
-// The plan-based runtime audits (Join/OrderBy/WhereClause index) are PostgreSQL-only, so remove their ITs for any
-// other engine. The catalog, JPA, and unconditional-mutation audits run on every engine; RepositoryWorkloadIT stays
-// too, because the unconditional-mutation audit throws on an empty capture, so its priming workload must still run.
+// The plan-based runtime audits (Join/OrderBy/Unused/WhereClause index) are PostgreSQL-only, so remove their ITs
+// for any other engine. The catalog, JPA, and capture-scan (offset-pagination/repeated-statement/
+// unconditional-mutation) audits run on every engine; RepositoryWorkloadIT stays too, because the
+// unconditional-mutation audit throws on an empty capture, so its priming workload must still run.
 def databasePlatform = request.properties.getProperty('databasePlatform', 'postgresql')
 if (databasePlatform != 'postgresql') {
     [
         "src/test/java/${packagePath}/runtime/JoinIndexAuditIT.java",
         "src/test/java/${packagePath}/runtime/OrderByIndexAuditIT.java",
+        "src/test/java/${packagePath}/runtime/UnusedIndexAuditIT.java",
         "src/test/java/${packagePath}/runtime/WhereClauseIndexAuditIT.java"
     ].each { path ->
         new File(destRoot, path).delete()
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/app/Child.java b/archetype/src/main/resources/archetype-resources/src/test/java/app/Child.java
@@ -9,11 +9,13 @@
 import jakarta.persistence.JoinColumn;
 import jakarta.persistence.ManyToOne;
 import jakarta.persistence.Table;
+import jakarta.persistence.Version;
 
 /**
  * Demo child entity whose {@code parent_id} foreign key is indexed, not null, and type-matched to
  * {@link Parent}'s primary key. Its {@code name} column is indexed so the example WHERE/ORDER BY audits see an
- * indexed access path.
+ * indexed access path. Carries a {@code @Version} attribute so concurrent updates are detected rather than
+ * silently overwritten.
  */
 @Entity
 @Table(name = "child")
@@ -30,6 +32,10 @@ public class Child {
     @JoinColumn(name = "parent_id", nullable = false)
     private Parent parent;
 
+    @Version
+    @Column(name = "version", nullable = false)
+    private int version;
+
     /**
      * Constructs an empty instance for JPA.
      */
@@ -73,4 +79,13 @@ public String getName() {
     public Parent getParent() {
         return parent;
     }
+
+    /**
+     * Returns the optimistic-locking version.
+     *
+     * @return the version.
+     */
+    public int getVersion() {
+        return version;
+    }
 }
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/app/Parent.java b/archetype/src/main/resources/archetype-resources/src/test/java/app/Parent.java
@@ -6,9 +6,11 @@
 import jakarta.persistence.GenerationType;
 import jakarta.persistence.Id;
 import jakarta.persistence.Table;
+import jakarta.persistence.Version;
 
 /**
- * Demo parent entity referenced by {@link Child} through an indexed, not-null, type-matched foreign key.
+ * Demo parent entity referenced by {@link Child} through an indexed, not-null, type-matched foreign key. Carries
+ * a {@code @Version} attribute so concurrent updates are detected rather than silently overwritten.
  */
 @Entity
 @Table(name = "parent")
@@ -21,6 +23,10 @@ public class Parent {
     @Column(name = "code", nullable = false)
     private String code;
 
+    @Version
+    @Column(name = "version", nullable = false)
+    private int version;
+
     /**
      * Constructs an empty instance for JPA.
      */
@@ -53,4 +59,13 @@ public Long getId() {
     public String getCode() {
         return code;
     }
+
+    /**
+     * Returns the optimistic-locking version.
+     *
+     * @return the version.
+     */
+    public int getVersion() {
+        return version;
+    }
 }
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/catalog/DuplicateForeignKeyAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/catalog/DuplicateForeignKeyAuditIT.java
@@ -0,0 +1,45 @@
+package ${package}.catalog;
+
+import java.util.Set;
+
+#if($disabledTests == 'true')
+import org.junit.jupiter.api.Disabled;
+#end
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+#set($simpleParentClass = $parentClass.replaceAll('.*\.', ''))
+import ${parentClass};
+#else
+import ${package}.AbstractDatabaseAuditIT;
+#end
+import io.github.databaseaudits.spring.boot.assertion.DuplicateForeignKeyAuditAssertion;
+
+/**
+ * Asserts that no relationship in the schema is enforced by more than one foreign key constraint, with a place
+ * to exclude a deliberate duplicate.
+ */
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+public class DuplicateForeignKeyAuditIT extends ${simpleParentClass} {
+#else
+public class DuplicateForeignKeyAuditIT extends AbstractDatabaseAuditIT {
+#end
+    /** Exclude a deliberate duplicate constraint, e.g. Set.of("fk_orders_customer_legacy"). */
+    private static final Set<String> EXCLUDED_CONSTRAINTS = Set.of();
+
+    @Autowired
+    private DuplicateForeignKeyAuditAssertion duplicateForeignKeyAuditAssertion;
+
+    @Value("#[[${]]#${schemaPropertyName}#[[}]]#")
+    private String schema;
+
+    @Test
+#if($disabledTests == 'true')
+    @Disabled("Generated as disabled; remove @Disabled to enable")
+#end
+    void testNoDuplicateForeignKeyConstraints() {
+        duplicateForeignKeyAuditAssertion.assertClean(schema, EXCLUDED_CONSTRAINTS);
+    }
+}
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/catalog/PrimaryKeyTypeAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/catalog/PrimaryKeyTypeAuditIT.java
@@ -0,0 +1,46 @@
+package ${package}.catalog;
+
+import java.util.Set;
+
+#if($disabledTests == 'true')
+import org.junit.jupiter.api.Disabled;
+#end
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+#set($simpleParentClass = $parentClass.replaceAll('.*\.', ''))
+import ${parentClass};
+#else
+import ${package}.AbstractDatabaseAuditIT;
+#end
+import io.github.databaseaudits.spring.boot.assertion.PrimaryKeyTypeAuditAssertion;
+
+/**
+ * Asserts that every primary key in the schema is at least bigint wide, with a place to exclude a genuinely
+ * bounded table.
+ */
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+public class PrimaryKeyTypeAuditIT extends ${simpleParentClass} {
+#else
+public class PrimaryKeyTypeAuditIT extends AbstractDatabaseAuditIT {
+#end
+    /** Liquibase's own bookkeeping table declares a narrow INT primary key; every application table here is
+     *  genuinely BIGINT. Add your own genuinely-bounded tables the same way, e.g. "lookup_values.id". */
+    private static final Set<String> EXCLUDED_COLUMNS = Set.of("databasechangeloglock.id");
+
+    @Autowired
+    private PrimaryKeyTypeAuditAssertion primaryKeyTypeAuditAssertion;
+
+    @Value("#[[${]]#${schemaPropertyName}#[[}]]#")
+    private String schema;
+
+    @Test
+#if($disabledTests == 'true')
+    @Disabled("Generated as disabled; remove @Disabled to enable")
+#end
+    void testEveryPrimaryKeyIsAtLeastBigint() {
+        primaryKeyTypeAuditAssertion.assertClean(schema, EXCLUDED_COLUMNS);
+    }
+}
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/catalog/UniqueIndexNotNullAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/catalog/UniqueIndexNotNullAuditIT.java
@@ -0,0 +1,45 @@
+package ${package}.catalog;
+
+import java.util.Set;
+
+#if($disabledTests == 'true')
+import org.junit.jupiter.api.Disabled;
+#end
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+#set($simpleParentClass = $parentClass.replaceAll('.*\.', ''))
+import ${parentClass};
+#else
+import ${package}.AbstractDatabaseAuditIT;
+#end
+import io.github.databaseaudits.spring.boot.assertion.UniqueIndexNotNullAuditAssertion;
+
+/**
+ * Asserts that no UNIQUE index in the schema includes a nullable column, with a place to exclude a deliberate
+ * partial-uniqueness design.
+ */
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+public class UniqueIndexNotNullAuditIT extends ${simpleParentClass} {
+#else
+public class UniqueIndexNotNullAuditIT extends AbstractDatabaseAuditIT {
+#end
+    /** Exclude a deliberate partial-uniqueness index, e.g. Set.of("uq_orders_active_customer"). */
+    private static final Set<String> EXCLUDED_INDEXES = Set.of();
+
+    @Autowired
+    private UniqueIndexNotNullAuditAssertion uniqueIndexNotNullAuditAssertion;
+
+    @Value("#[[${]]#${schemaPropertyName}#[[}]]#")
+    private String schema;
+
+    @Test
+#if($disabledTests == 'true')
+    @Disabled("Generated as disabled; remove @Disabled to enable")
+#end
+    void testNoUniqueIndexOverNullableColumn() {
+        uniqueIndexNotNullAuditAssertion.assertClean(schema, EXCLUDED_INDEXES);
+    }
+}
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/jpa/EagerCollectionFetchAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/jpa/EagerCollectionFetchAuditIT.java
@@ -0,0 +1,40 @@
+package ${package}.jpa;
+
+import java.util.Set;
+
+#if($disabledTests == 'true')
+import org.junit.jupiter.api.Disabled;
+#end
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+#set($simpleParentClass = $parentClass.replaceAll('.*\.', ''))
+import ${parentClass};
+#else
+import ${package}.AbstractDatabaseAuditIT;
+#end
+import io.github.databaseaudits.spring.boot.assertion.EagerCollectionFetchAuditAssertion;
+
+/**
+ * Asserts that no mapped collection is fetched eagerly, with a place to exclude a deliberately eager one.
+ */
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+public class EagerCollectionFetchAuditIT extends ${simpleParentClass} {
+#else
+public class EagerCollectionFetchAuditIT extends AbstractDatabaseAuditIT {
+#end
+    /** Exclude a deliberately eager collection role, e.g. Set.of("com.example.demo.Order.items"). */
+    private static final Set<String> EXCLUDED_ROLES = Set.of();
+
+    @Autowired
+    private EagerCollectionFetchAuditAssertion eagerCollectionFetchAuditAssertion;
+
+    @Test
+#if($disabledTests == 'true')
+    @Disabled("Generated as disabled; remove @Disabled to enable")
+#end
+    void testNoCollectionIsFetchedEagerly() {
+        eagerCollectionFetchAuditAssertion.assertClean(EXCLUDED_ROLES);
+    }
+}
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/jpa/MissingVersionAttributeAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/jpa/MissingVersionAttributeAuditIT.java
@@ -0,0 +1,41 @@
+package ${package}.jpa;
+
+import java.util.Set;
+
+#if($disabledTests == 'true')
+import org.junit.jupiter.api.Disabled;
+#end
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+#set($simpleParentClass = $parentClass.replaceAll('.*\.', ''))
+import ${parentClass};
+#else
+import ${package}.AbstractDatabaseAuditIT;
+#end
+import io.github.databaseaudits.spring.boot.assertion.MissingVersionAttributeAuditAssertion;
+
+/**
+ * Asserts that every mutable root entity carries a {@code @Version} attribute, with a place to exclude a
+ * genuinely append-only or single-writer entity.
+ */
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+public class MissingVersionAttributeAuditIT extends ${simpleParentClass} {
+#else
+public class MissingVersionAttributeAuditIT extends AbstractDatabaseAuditIT {
+#end
+    /** Exclude an append-only or single-writer entity, e.g. Set.of("com.example.demo.AuditLogEntry"). */
+    private static final Set<String> EXCLUDED_ENTITIES = Set.of();
+
+    @Autowired
+    private MissingVersionAttributeAuditAssertion missingVersionAttributeAuditAssertion;
+
+    @Test
+#if($disabledTests == 'true')
+    @Disabled("Generated as disabled; remove @Disabled to enable")
+#end
+    void testEveryMutableEntityIsVersioned() {
+        missingVersionAttributeAuditAssertion.assertClean(EXCLUDED_ENTITIES);
+    }
+}
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/jpa/UnmappedDatabaseObjectAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/jpa/UnmappedDatabaseObjectAuditIT.java
@@ -0,0 +1,43 @@
+package ${package}.jpa;
+
+import java.util.Set;
+
+#if($disabledTests == 'true')
+import org.junit.jupiter.api.Disabled;
+#end
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+#set($simpleParentClass = $parentClass.replaceAll('.*\.', ''))
+import ${parentClass};
+#else
+import ${package}.AbstractDatabaseAuditIT;
+#end
+import io.github.databaseaudits.spring.boot.assertion.UnmappedDatabaseObjectAuditAssertion;
+
+/**
+ * Asserts that every physical base table and column in the live schema is mapped by a JPA entity, with a place
+ * to exclude a known, acceptable unmapped relation (e.g. a migration-tool bookkeeping table).
+ */
+#if($parentClass && $parentClass != '' && $parentClass != 'none')
+public class UnmappedDatabaseObjectAuditIT extends ${simpleParentClass} {
+#else
+public class UnmappedDatabaseObjectAuditIT extends AbstractDatabaseAuditIT {
+#end
+    /** Liquibase's own bookkeeping tables track migrations, not application data, so no entity should map them.
+     *  Add your own known, acceptable unmapped relations the same way. */
+    private static final Set<String> EXCLUDED_RELATIONS =
+            Set.of("databasechangelog", "databasechangeloglock");
+
+    @Autowired
+    private UnmappedDatabaseObjectAuditAssertion unmappedDatabaseObjectAuditAssertion;
+
+    @Test
+#if($disabledTests == 'true')
+    @Disabled("Generated as disabled; remove @Disabled to enable")
+#end
+    void testEveryDatabaseObjectIsMapped() {
+        unmappedDatabaseObjectAuditAssertion.assertClean(EXCLUDED_RELATIONS);
+    }
+}
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/runtime/OffsetPaginationAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/runtime/OffsetPaginationAuditIT.java
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/runtime/RepeatedStatementAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/runtime/RepeatedStatementAuditIT.java
diff --git a/archetype/src/main/resources/archetype-resources/src/test/java/runtime/UnusedIndexAuditIT.java b/archetype/src/main/resources/archetype-resources/src/test/java/runtime/UnusedIndexAuditIT.java
diff --git a/archetype/src/main/resources/archetype-resources/src/test/resources/db/changelog/db.changelog-master.xml b/archetype/src/main/resources/archetype-resources/src/test/resources/db/changelog/db.changelog-master.xml
