Rule Executor
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.