Annotations Guide¶

@SpringBootTest
@QueryAudit
class OrderServiceTest {

    @Test
    void findOrders() {
        // Analyze SELECT/INSERT/UPDATE/DELETE captured through the audited DataSource.
        // Test fails if any confirmed issue (ERROR or WARNING) is detected.
    }
}

@QueryAudit(nPlusOneThreshold = 5)  // Class-level: applies to all tests
@SpringBootTest
class OrderServiceTest {

    @Test
    void findOrders() {
        // Uses class-level config: threshold=5, failOnDetection=true
    }

    @QueryAudit(failOnDetection = BooleanOverride.FALSE)  // Method-level: overrides entire class config
    @Test
    void exportAll() {
        // Report only for this specific test.
        // nPlusOneThreshold reverts to default (3), NOT the class-level 5,
        // because method-level replaces (not merges) the class-level settings.
    }

    @QueryAudit(nPlusOneThreshold = 2, suppress = {"select-all"})
    @Test
    void findTopOrders() {
        // Method-level: strict threshold, select-all suppressed.
        // Class-level threshold of 5 is ignored.
    }
}

@SpringBootTest
@EnableQueryInspector
class OrderServiceTest {

    @Test
    void findOrders() {
        // Reports detected findings without making those findings fatal.
        // Explicit budgets and contracts still apply.
    }
}

@QueryAuditExclude   // intentionally replays thousands of single-row inserts
class SeedDataReplayTest { ... }

@QueryAudit
class OrderServiceTest {

    @Test
    void findOrders() { ... }          // audited

    @QueryAuditExclude
    @Test
    void bulkFixtureReplay() { ... }   // skipped
}

@SpringBootTest
@DetectNPlusOne
class OrderServiceTest {

    @Test
    void findOrdersWithItems() {
        List<Order> orders = orderService.findAll();
        for (Order order : orders) {
            order.getItems().size();  // N+1! Test will fail.
        }
    }

    @Test
    void findSingleOrder() {
        orderService.findById(1L);
        // No N+1 here, test passes.
        // Other issues (e.g., SELECT *) are reported but don't fail.
    }
}

@SpringBootTest
@QueryAudit  // Full analysis for most tests
class OrderServiceTest {

    @DetectNPlusOne(threshold = 2)  // Only fail on N+1 for this specific test
    @Test
    void findOrdersWithItems() {
        List<Order> orders = orderService.findAll();
        for (Order order : orders) {
            order.getItems().size();
        }
    }
}

@SpringBootTest
@QueryAudit
class OrderServiceTest {

    @Test
    @ExpectMaxQueryCount(5)
    void createOrder() {
        orderService.createOrder(request);
        // Fails if more than 5 total queries are executed
    }

    @Test
    @ExpectMaxQueryCount(3)
    void findOrderById() {
        orderService.findById(1L);
        // Ensures a simple lookup stays efficient
    }
}

@SpringBootTest
@QueryAudit
class OrderServiceTest {

    @Test
    @ExpectQueries(select = 2, insert = 1)
    void createOrder() {
        orderService.createOrder(request);
        // Fails if more than 2 SELECTs or more than 1 INSERT are executed
    }

    @Test
    @ExpectQueries(insert = 0, update = 0, delete = 0)
    void findOrderById() {
        orderService.findById(1L);
        // A captured INSERT, UPDATE, or DELETE fails this budget.
    }
}

@Test
@ExpectQueries(select = 2, insert = 0, exact = true)
void findOrderWithCustomer() {
    orderService.findWithCustomer(1L);
    // Fails on one SELECT as well as on three. UPDATE and DELETE stay unchecked.
}

@SpringBootTest
@QueryAudit(nPlusOneThreshold = 2)  // Fail on N+1 from the second repetition
class OrderServiceTest {

    @Test
    @ExpectQueries(total = 10, update = 0)  // Also enforce budgets
    void createOrder() {
        orderService.createOrder(request);
    }

    @Test
    void findOrders() {
        // Only the class-level @QueryAudit applies here
        orderService.findAll();
    }
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@SpringBootTest
@QueryAudit
public @interface AuditedIntegrationTest {}

@AuditedIntegrationTest
class OrderServiceTest { ... }

@QueryAudit
abstract class AuditedTestBase { ... }

class PaymentServiceTest extends AuditedTestBase { ... }

@QueryAudit
class OrderRepositoryTest {

    static DataSource dataSource =
            ProxyDataSourceBuilder.create(new HikariDataSource(hikariConfig()))
                    .name("query-audit")
                    .build();

    @Test
    void findByStatus() {
        try (Connection conn = dataSource.getConnection()) {
            PreparedStatement ps = conn.prepareStatement(
                "SELECT * FROM orders WHERE status = ?");
            ps.setString(1, "PENDING");
            ResultSet rs = ps.executeQuery();
            // This connection comes from the discovered proxy.
        }
    }

    private static HikariConfig hikariConfig() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:mysql://localhost:3306/test");
        config.setUsername("root");
        config.setPassword("password");
        return config;
    }
}