test_detective

Unit testing Java rule engines built on Drools

Rule engines are wonderfully expressive tools for capturing business logic, yet they tend to be under-tested because their behaviour is dynamic, their internal state is mutable, and they often sit deep inside a transaction or workflow that is hard to reproduce in isolation. When a finance platform in Sydney processes a loan application, the underlying decision logic frequently lives in a Drools knowledge base rather than scattered through hundreds of conditional statements. Unit tests for that logic therefore need to interrogate the engine itself, not just the code that calls it. Learn more about Testing Soap Web Services With Spring Ws And Mockwebserviceserver 283514.

Java developers who lean on Drools for tax calculations, eligibility checks or compliance scoring typically discover that ordinary JUnit scaffolding is not enough. The engine maintains facts in working memory, fires rules according to agenda groups, and may mutate state between calls. A test that simply fires rules and checks the output misses out on whether the right rule fired, in the right order, with the right consequences. Below is a practical approach to filling those gaps with focused, deterministic unit tests.

Why rule engines deserve their own test strategy

Most teams treat Drools as a black box: build a session, drop a fact in, fire rules, read the result. The problem with that attitude is that a rule engine is essentially a forward-chaining inference machine. Inserting one fact can cascade into several rule activations, and a single test that asserts a final value rarely catches the rule that did the wrong work in the middle. In an Australian context, think of the Australian Taxation Office's payroll tax thresholds, or the Goods and Services Tax exemptions for certain categories of imported goods: the rule sets look small, but every branch needs coverage.

A second reason is agenda pollution. A KieSession retains facts across calls, which is great for long-running processes and a nightmare for repeatable tests. Without disciplined teardown, one test can leak facts into another, producing flaky runs that engineers in Brisbane or Melbourne eventually blame on the CI server. Treat every rule test the same way you would treat a database integration test: clear state, insert only what is needed, assert on what fired, dispose.

Anatomy of a Drools test

Before writing any assertions, it helps to know the moving parts. A KieServices.Factory.get() gives access to a KieContainer, which in turn produces KieSession or StatelessKieSession instances. Each session wraps a KieBase, the compiled rule set, plus the working memory where facts live. The session exposes insert, update, delete, fireAllRules, and the agenda listener interfaces used for verification.

Most teams bootstrap Drools with a kmodule.xml file in src/main/resources/META-INF, pointing at one or more KieBase definitions. In a unit test, that bootstrapping still runs because the container is read from the classpath. The first thing a good test does is grab a session explicitly scoped for that test class, so unrelated KieBase changes do not quietly break assertions on the other side of town.

DRL and decision tables as first-class subjects

The rules themselves live in .drl files, decision tables (.xls or .csv), or, more recently, rule units written in Java or DMN files. Each format deserves direct test coverage rather than relying on a higher-level integration test to catch typos in a regex or a missing semicolon. A common pattern is to write a Java test that mirrors each rule with a specific fact scenario.

For decision tables, an effective approach is to parameterise the test class. Take a CSV of rule scenarios, including input facts, expected rule fired and expected outcome, and feed it through a JUnit Parameterized runner or a TestNG data provider. This way, a rule added by a business analyst in Adelaide shows up immediately as a missing row in the test report, not as a silent gap discovered three months later during reconciliation.

Inserting facts without tearing your hair out

Facts are usually plain Java objects, sometimes annotated with Drools metadata such as @role, @timestamp, or @expires for event-driven scenarios. The test code is straightforward: build the POJO, hand it to the session, fire the rules, read what changed. The trick is to use a builder or a fixture method per fact type so the test reads as a narrative: "Given a customer under 25 with a first-home loan application, when the engine runs, then the stamp duty waiver rule fires."

That Given-When-Then style mirrors BDD and makes the tests easy to review with non-technical stakeholders, which is a genuine benefit when working with the business teams that often own the rule definitions in the first place. A side benefit: when someone breaks a rule, the test name reads like a sentence and points straight at the regression.

Asserting what actually fired

Knowing the output is not the same as knowing why. Drools exposes an AgendaEventListener that can be attached to a session and capture every rule activation and match. Inside a test, that listener can be used to populate a list of fired rule names. Asserting on that list is what turns a rule engine test from "did the answer change" into "did the right rule change the answer".

In practice, a small test helper that wraps fireAllRules, records the match events, and returns the names is enough. The helper can be reused across dozens of tests, and it stops you from writing the same boilerplate twenty times. It also gives you a stable place to log rule firings during debugging, which saves hours when a new rule inadvertently shadows an older one.

Stateful sessions versus stateless sessions

The choice between KieSession and StatelessKieSession is one of the most common decisions a team makes, and the test strategy differs accordingly. Stateful sessions remember everything you put in them, support incremental reasoning, and need explicit dispose() calls in a finally block. Stateless sessions are fire-and-forget; everything is discarded after execute() returns.

Aspect Stateful KieSession Stateless StatelessKieSession
Working memory Persists between fireAllRules() calls Cleared after execute() returns
Best fit for Long-running processes, event streams, complex inference One-shot decisions, REST endpoints, batch scoring
Disposal Mandatory dispose() in a finally block Automatic
Test isolation concern High; facts leak across calls if not cleared Low; fresh working memory per execution
Common Australian use case Medicare claims adjudication, NDIS plan reasoning GST calculation, payroll tax threshold checks
Agenda listener support Full, including before and after match events Limited to a single execution snapshot

Picking the wrong flavour for the wrong job leads to memory leaks and surprising behaviour. The same applies to tests: stateful session tests must always dispose, and stateless session tests can be slimmer because each call is naturally isolated.

Integrating with Spring and mocking the engine

When Drools is wired into a Spring Boot service, the temptation is to spin up the full container in every test. That works but slows things down, especially when the knowledge base is large. For service-layer tests that do not care about rule internals, mocking KieSession with Mockito keeps the feedback loop quick.

Two complementary strategies work well together. Mock the session when the test's purpose is the surrounding service logic: HTTP mapping, transaction boundaries, error handling. Use real sessions when the test's purpose is the rules themselves. A test that mixes both concerns often ends up asserting nothing meaningful. The same discipline applies elsewhere in the Java ecosystem; if you have ever wrestled with SOAP endpoint testing in Spring, the Testing SOAP Web Services with Spring WS and MockWebServiceServer piece on Test Detective walks through a very similar split.

If you find yourself needing deeper coverage of dynamic rule changes or hot reloading, Mike Meredith's blog carries some pragmatic write-ups on production Drools deployments that complement a unit-testing focus nicely.

Practical habits for a reliable Drools test suite

A Drools unit test is not just a JUnit test with a Drools dependency. It is a tiny, self-contained inference machine you can poke at, fire rules into, and dispose of cleanly. Treat the session like a database, the agenda like a log you can assert on, and the rule file itself as code that deserves direct coverage. Once that mindset is in place, rule engines stop being the flaky corner of the codebase and start behaving like any other well-tested Java component, a difference that matters whether the team sits in the Sydney CBD, in Perth, or in whichever office owns the rules on a given afternoon.