Fluent Commerce Logo
Docs
Essential knowledgeCore knowledge to understand Fluent Commerce

Intended Audience:

Technical User

Author:

Kirill Gaiduk

Changed on:

5 Sept 2025

Overview

The `RuleExecutor` is the primary tool in the `util-test` library for unit testing a single rule in isolation. It provides a builder-style interface for setting up a mock `Context`, executing your rule's `run` method, and asserting the results.

Key points

  • Unit Testing Focus: `RuleExecutor` is the main tool for testing a single rule in isolation.
  • Arrange-Act-Assert: It's designed to follow the clean Arrange-Act-Assert pattern. You use the constructor to arrange the context, call `execute()` to act, and use `getActions()` to assert the outcome.
  • Rule Properties Configuration: Rule properties are passed as a `Map` in the `RuleExecutor.of(Class, Map)` constructor.
  • Event Configuration: Custom events can be passed to the `execute(Event)` method.
  • GraphQL Mocking: The `.mockNamedQuery()` method is a critical feature that allows you to provide predefined JSON responses for any GraphQL query your rule executes, enabling you to test different data scenarios without making live API calls.

Arrange-Act-Assert

Testing with `RuleExecutor` follows the standard Arrange-Act-Assert pattern, which makes tests clean and easy to understand by clearly separating each phase:
Arrange (Build the Context)
This is the setup phase where you define all the conditions for your test case. You start by calling `RuleExecutor.of(MyRule.class, Map)`  with rule properties.
Act (Execute the Rule)
This is the simplest step. The `execute()` method runs your rule's `run` method using the mock context you just configured.You can pass a custom event if needed. You can pass a custom event if needed.
Assert (Verify the Outcome)
After execution, you can retrieve the actions that your rule performed and use the built-in fluent assertions to verify them.

Core Methods

`of` (ruleName, props)
To create a `RuleExecutor` for a rule specified by its name, use the `RuleExecutor.of` method passing the specific name of the Rule.
`of` (className, props)
To create a RuleExecutor for a rule specified by its class, use the RuleExecutor.of method passing the specific rule class. 
`execute` (event)
If you need to execute a Rule with an Event containing attributes or entity details, use the `RuleExecutor` to pass in the customized Event. Any null fields will be auto-populated with values referencing an Order entity.
`resetApi`
Use the `RuleExecutor.resetApi` method to create a new API mock and clear any previously mocked queries. This allows you to start each test with a clean slate and ensures that previous mocks do not interfere with the current test execution.
`replaceApi`
To replace the executor’s API mock with your own MockApiClient, use the `RuleExecutor.replaceApi` method. This allows you to reuse the same mock configuration across multiple tests, ensuring consistency and reducing setup overhead.
`withLegacyClient` 
To use the provided legacy client instead of a stubbed one, utilize the `RuleExecutor.withLegacyClient` method. This enables you to connect to a real client for more accurate testing or simulate a specific client setup during the execution.

Complete Example