trools: A test framework for rules.

Authored and maintained by Daniel Akiva and Derek Abdine (derek abdine gmail dot com).

Why trools?

The primary goal is to build a framework that focuses on quickly bringing test cases online without having to mess with boilerplate code for configuring a rules environment. We want to be able to write tests that are portable between rules engines so that migrating from one engine to another without breaking rules can be done with confidence.

Alternatives

Some rules engines have been integrated with Spring. A similar approach to what trools provides can be exposed by working with Spring's support for JSR-94 and specific rule engine implementations. Trools was designed to be spring-agnostic.

Engine support

Extending trools to support other rules engines is a trivial task. Please submit a ticket if you'd like to see support for other JSR-94 rules engines. The currently supported engines are:

• Drools
• Jess

Quick start

Below are a couple examples to help you get started. Keep in mind that the test logic has not changed between the jess/drools examples -- only the test class configuration (by way of annotations) and the rule language has changed. This helps facilitate test-driven development for rules.

Dependencies

Trools depends on JUnit 4.1+ and the JSR-94 specification, as well as a plugin JSR-94 implementation (aka rules engine). As of October 17th 2013, trools is an official Sonatype OSS project and is synchronized with the Maven central repository. The maven dependency configuration would look like:

   <dependencies>
      <dependency>
         <groupId>com.rapid7.trools</groupId>
         <artifactId>trools-core</artifactId>
         <version>1.0</version>
         <scope>test</scope>
      </dependency>
   </dependencies>

Jess (https://github.com/dabdine/trools-examples-jess)

Create your rules file:

(defclass Person org.rapid7.trools.jess.example.fact.Person static)

(defrule simple-test
   ?personFact <- (Person
      (name ?name &: (eq ?name "Bill")))
=>
   (retract ?personFact)
   (add (new String "hello world"))
)

Create a trools-powered stateless rule session test case:

@RunWith(JessRulesJUnit4ClassRunner.class)
@RuleContext(resourceURI = "org/rapid7/trools/jess/example/simple-test.clp")
public class StatelessExampleTest {
    @Test
    public void statelessExample() throws InvalidRuleSessionException,
            RemoteException {
        // when
        List results = m_ruleSession.executeRules(Arrays.asList(new Person().setName("Bill")));
    
        // then
        assertEquals("hello world", results.get(0));
    }

    @InjectRuleSession
    private StatelessRuleSession m_ruleSession;
}

OR create a trools-powered stateful rule session test case:

@RunWith(JessRulesJUnit4ClassRunner.class)
@RuleContext(resourceURI = "org/rapid7/trools/jess/example/simple-test.clp")
public class StatefulExampleTest {
    @Test
    public void statefulExample() throws InvalidRuleSessionException,
            RemoteException {
        // given
        m_ruleSession.addObject(new Person().setName("Bill"));
    
        // when
        m_ruleSession.executeRules();
    
        // then
        List results = m_ruleSession.getObjects(new ClassTypeObjectFilter(
            String.class));
        assertEquals("hello world", results.get(0));
    }

    @InjectRuleSession
    private StatefulRuleSession m_ruleSession;
}

Drools (https://github.com/dabdine/trools-examples-drools)

Create your rules file:

package org.rapid7.trools.example; 
import org.rapid7.trools.example.Person;

rule "simple-test"
    when 
        p : Person ( name == "Bill" )  
    then 
        retract(p);
        insert(new String("hello world"));
end

Create a trools-powered stateless rule session test case:

@RunWith(DroolsJUnit4ClassRunner.class)
@RuleContext(resourceURI = "org/rapid7/trools/drools/example/simple-test.drl")
public class StatelessExampleTest {
    @Test
    public void statelessExample() throws InvalidRuleSessionException,
            RemoteException {
        // when
        List results = m_ruleSession.executeRules(Arrays.asList(new Person().setName("Bill")));
    
        // then
        assertEquals("hello world", results.get(0));
    }

    @InjectRuleSession
    private StatelessRuleSession m_ruleSession;
}

OR create a trools-powered stateful rule session test case:

@RunWith(DroolsJUnit4ClassRunner.class)
@RuleContext(resourceURI = "org/rapid7/trools/drools/example/simple-test.drl")
public class StatefulExampleTest {
    @Test
    public void statefulExample() throws InvalidRuleSessionException,
            RemoteException {
        // given
        m_ruleSession.addObject(new Person().setName("Bill"));
    
        // when
        m_ruleSession.executeRules();
    
        // then
        List results = m_ruleSession.getObjects(new ClassTypeObjectFilter(
            String.class));
        assertEquals("hello world", results.get(0));
    }

    @InjectRuleSession
    private StatefulRuleSession m_ruleSession;
}

That's it. Run the test cases and you should see results :) For more interesting test cases, try combining mockito mock objects with trools test cases by passing the mock objects to the StatefulRuleSession#addObject(Object) or StatelessRuleSession#executeRules(List) methods, which can then be used by your rules and verified in the unit test methods.

Contributing

We need support for other rules engines!

When making contributions, please use Java coding standards. If using Eclipse to develop changes, these standards are built in and can be turned on in the Eclipse project Java code style settings configuration page.

Licensing

This project is available under the MIT license.