judo-integration-testing-docs

name	judo-integration-testing-docs
description	Integration testing guide for JUDO backend. Covers testkit usage, test patterns, and custom operation testing.
disable-model-invocation	false
user-invocable	false
model	inherit
context	fork
agent	general-purpose

Integration Testing Guide

Overview

This guide covers integration testing for custom business logic in northwind. It focuses on using the judo-runtime-core-testkit to test custom operations, interceptors, and validators.

For a complete understanding of the backend architecture, code generation, and custom implementation patterns, please refer to the main Backend Development Guide (see judo-backend-docs skill).

Note: Throughout this document, northwind refers to the application name from judo.properties (app_name property). Package names, file paths, and generated artifacts use this value.

Prerequisites

Required Tool Versions

This project uses SDKMAN for version management. Required versions are specified in .sdkmanrc:

java=21.0.7-zulu
maven=3.9.10
mvnd=1.0.2

Setup:

# 1. Install SDKMAN (if not already installed)
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 2. Enable auto-env (recommended - automatic version switching)
echo "sdkman_auto_env=true" >> ~/.sdkman/etc/config

# 3. Install versions from .sdkmanrc
cd [project-name]
sdk env install

# 4. Verify
java -version   # Should show 21.0.7-zulu
mvn -version    # Should show 3.9.10

How It Works:

• .sdkmanrc is generated by ./judo.sh generate-root command
• When sdkman_auto_env=true, SDKMAN automatically switches to project versions when you enter the directory
• ./judo.sh script automatically installs required versions if missing

Maven Daemon (mvnd): Optional but recommended for faster builds

# Use mvnd instead of mvn for faster incremental builds
mvnd clean install

Related Documentation

For comprehensive information on backend development, please see the Backend Development Guide (see judo-backend-docs skill).

• Getting Started with Integration Testing - An introduction to the testkit and writing your first test.
• Best Practices for Integration Testing - Guidelines for writing effective and maintainable tests.
• Advanced Integration Testing Patterns - Advanced techniques for complex testing scenarios.
• Testing Access Rules and DERIVED Attributes - Pattern A (DAO-projected derived attributes), Pattern B (Access.getterExpression per actor via Dispatcher), Pattern C (DERIVED getters that read ACTOR.*). Closes the gap between entity-level DAO tests and full E2E.
• Supplementary Testing Patterns - Additional patterns and examples.
• Type Safety in Integration Tests - Ensuring type safety in your tests.
• OSGi DS Descriptor Contract Tests - Verify @Reference target filters, cardinality, policy, and service properties by asserting against the SCR component XML descriptors emitted by maven-bundle-plugin. Needed because OSGi's @Reference annotation has CLASS retention and is invisible to reflection / the Guice testkit.