Rule Engine Testing Guide

Testing rules requires a layered approach: unit tests validate rule logic in isolation, integration tests verify orchestrator execution and data flow, and API tests confirm runtime behavior with approval workflows and persistence.

Overview

The Muonroi rule engine provides three distinct testing patterns:

1. Unit tests — validate individual rules with MRuleOrchestratorSpy
2. Integration tests — verify orchestrator execution, dependencies, and FactBag state
3. API tests — confirm ruleset lifecycle (save → approve → activate) and SignalR notifications

All test infrastructure is in the Muonroi.RuleEngine.Testing NuGet package.

---

Unit Testing with MRuleOrchestratorSpy

MRuleOrchestratorSpy<TContext> is a test wrapper that captures rule execution records and fact changes without requiring a database.

Basic Usage

using Muonroi.RuleEngine.Testing;
using Xunit;

[Fact]
public async Task MyRule_ShouldSetFactValue()
{
    // Arrange
    var rules = new List<IRule<string>> { new MyRule() };
    var spy = new MRuleOrchestratorSpy<string>(rules);

    // Act
    FactBag facts = await spy.ExecuteAsync("input-context");

    // Assert
    Assert.NotEmpty(spy.ExecutionRecords);
    Assert.Equal("RULE001", spy.ExecutionRecords[0].RuleCode);
    Assert.True(spy.ExecutionRecords[0].IsSuccess);
    Assert.Equal("expected-value", facts["my-fact"]);
}

public class MyRule : IRule<string>
{
    public string Code => "RULE001";
    public int Order => 1;

    public async Task<RuleResult> EvaluateAsync(
        string context,
        FactBag facts,
        CancellationToken ct = default)
    {
        // Condition check (returns failure if not met)
        if (context == null)
            return await Task.FromResult(RuleResult.Failure("context required"));

        return await Task.FromResult(RuleResult.Passed());
    }

    public Task ExecuteAsync(string context, CancellationToken cancellationToken = default)
    {
        // Side effects — update FactBag (phase 2)
        // Note: FactBag is passed implicitly via orchestrator
        return Task.CompletedTask;
    }
}

Spy Features

MRuleOrchestratorSpy<TContext> provides:

• ExecutionRecords — IReadOnlyList<MRuleExecutionRecord> containing rule code, success flag, duration, and fact changes
• AfterSnapshot — complete FactBag state after execution
• BeforeSnapshot — FactBag state before execution (for before/after comparison)

Asserting FactBag Changes

[Fact]
public async Task MyRule_ShouldModifyFactBag()
{
    var rules = new List<IRule<string>> { new MyRule() };
    var spy = new MRuleOrchestratorSpy<string>(rules);

    await spy.ExecuteAsync("ctx");

    // Assert keys exist and have expected values
    Assert.True(spy.AfterSnapshot.ContainsKey("output-key"));
    Assert.Equal("calculated-value", spy.AfterSnapshot["output-key"]);

    // Assert specific fact changes
    var record = spy.ExecutionRecords[0];
    Assert.True(record.Changes.ContainsKey("output-key"));
    var (oldValue, newValue) = record.Changes["output-key"];
    Assert.Null(oldValue);
    Assert.Equal("calculated-value", newValue);
}

---

Integration Testing with RuleOrchestrator

Test orchestrator behavior: dependency resolution, execution order, failure handling, and multi-tenant context propagation.

Dependency Resolution

[Fact]
public async Task ExecuteAsync_ResolvesDependenciesInOrder()
{
    var executed = new List<string>();

    var ruleB = new TestRule(
        code: "B",
        action: facts =>
        {
            facts["result"] = 42;
            executed.Add("B");
            return Task.FromResult(RuleResult.Success());
        });

    var ruleA = new TestRule(
        code: "A",
        dependencies: [typeof(TestRule)],  // B must execute first
        action: facts =>
        {
            if (!facts.TryGet("result", out int value) || value != 42)
                return Task.FromResult(RuleResult.Failure("B did not run"));
            executed.Add("A");
            return Task.FromResult(RuleResult.Success());
        });

    var orchestrator = new RuleOrchestrator<object>(
        new IRule<object>[] { ruleA, ruleB },
        hooks: [],
        logger: new NullLogger<RuleOrchestrator<object>>());

    await orchestrator.ExecuteAsync(new object());

    // B executes first due to dependency, then A
    Assert.Equal(new[] { "B", "A" }, executed);
}

Execution Order (Order Property Fallback)

When no dependencies exist, rules execute in order of their Order property (ascending):

[Fact]
public async Task ExecuteAsync_UsesOrderAsFallback()
{
    var executed = new List<string>();

    var second = new TestRule(code: "SECOND", order: 20);
    var first = new TestRule(code: "FIRST", order: 10);

    var orchestrator = CreateOrchestrator(second, first);
    await orchestrator.ExecuteAsync(new object());

    Assert.Equal(new[] { "FIRST", "SECOND" }, executed);
}

Cycle Detection

The orchestrator detects circular dependencies and throws InvalidOperationException:

[Fact]
public void ExecuteAsync_DetectsCycle()
{
    var ruleA = new TestRule("A", dependencies: [typeof(TestRule<RuleB>)]);
    var ruleB = new TestRule("B", dependencies: [typeof(TestRule<RuleA>)]);

    // Throws during construction (Kahn's algorithm validation)
    Assert.Throws<InvalidOperationException>(() =>
        new RuleOrchestrator<object>(new IRule<object>[] { ruleA, ruleB }, [], null));
}

Failure Handling (AllOrNothing Mode)

By default, the orchestrator stops on first failure and propagates the error:

[Fact]
public async Task ExecuteAsync_ShortCircuitsOnFailure()
{
    var executed = new List<string>();

    var failingRule = new TestRule(
        code: "FAIL",
        action: _ =>
        {
            executed.Add("FAIL");
            return Task.FromResult(RuleResult.Failure("boom"));
        });

    var laterRule = new TestRule(
        code: "LATER",
        action: _ =>
        {
            executed.Add("LATER");  // Never executes
            return Task.FromResult(RuleResult.Success());
        });

    var orchestrator = CreateOrchestrator(failingRule, laterRule);

    // Throws InvalidOperationException
    await Assert.ThrowsAsync<InvalidOperationException>(
        () => orchestrator.ExecuteAsync(new object()));

    Assert.Equal(new[] { "FAIL" }, executed);
}

---

Multi-Tenant Testing

Test tenant-scoped rules with keyed service resolution and TenantRuleGroup attribute.

Tenant-Scoped Rule Registration

[TenantRuleGroup("workflow-name", "tenant-id")]
public sealed class TenantScopedRule : IRule<string>
{
    public string Code => "TENANT_RULE";
    public int Order => 0;

    public Task<RuleResult> EvaluateAsync(
        string context,
        FactBag facts,
        CancellationToken ct)
    {
        facts["tenant"] = "tenant-id";
        return Task.FromResult(RuleResult.Passed());
    }

    public Task ExecuteAsync(string context, CancellationToken ct = default)
        => Task.CompletedTask;
}

[Fact]
public async Task ResolveKeyedOrchestrator_ForTenant()
{
    var services = new ServiceCollection();
    services.AddLogging();
    services.AddRuleEngine();

    // Register rule scoped to workflow + tenant
    services.AddScoped<TenantScopedRule>();
    services.AddKeyedScoped<IRule<string>, TenantScopedRule>("workflow:tenant-id");

    // Register keyed orchestrator that pulls keyed rules
    services.AddKeyedScoped("workflow:tenant-id", (sp, _) =>
        new RuleOrchestrator<string>(
            sp.GetRequiredKeyedService<IEnumerable<IRule<string>>>("workflow:tenant-id"),
            sp.GetKeyedService<IEnumerable<IHookHandler<string>>>("workflow:tenant-id") ?? [],
            sp.GetService<IMLog<RuleOrchestrator<string>>>()));

    var provider = services.BuildServiceProvider();
    var orchestrator = provider.GetRequiredKeyedService<RuleOrchestrator<string>>("workflow:tenant-id");

    var facts = await orchestrator.ExecuteAsync("ctx");

    Assert.Equal("tenant-id", facts["tenant"]);
}

---

API Testing: Ruleset Lifecycle

Test the complete workflow: save version → submit for approval → approve → activate → verify persistence.

Save and Activate a Ruleset

using Muonroi.ControlPlane.Sdk;
using Xunit;

[Fact]
public async Task RulesetLifecycle_SaveAndActivate()
{
    var client = new ControlPlaneApiClient("https://cp.example.com");
    var workflowName = "test-workflow-" + Guid.NewGuid();

    // Step 1: Build ruleset JSON
    var ruleset = new
    {
        rules = new[] {
            new {
                code = "RULE001",
                name = "Test Rule",
                condition = "input.value > 100",
                actions = new[] {
                    new { type = "set-fact", key = "status", value = "approved" }
                }
            }
        },
        settings = new { executionMode = "AllOrNothing" }
    };

    // Step 2: Save new version (draft)
    var saveResponse = await client.Rulesets.SaveAsync(workflowName, ruleset);
    int version = saveResponse.Version;
    Assert.Equal("draft", saveResponse.Status);

    // Step 3: Submit for approval (if approval required)
    var submitResponse = await client.Rulesets.SubmitForApprovalAsync(workflowName, version);
    Assert.Equal("submitted", submitResponse.Status);

    // Step 4: Approve
    var approveResponse = await client.Rulesets.ApproveAsync(workflowName, version);
    Assert.Equal("approved", approveResponse.Status);

    // Step 5: Activate
    var activateResponse = await client.Rulesets.ActivateAsync(workflowName, version);
    Assert.Equal("active", activateResponse.Status);

    // Verify active version
    var activeRuleset = await client.Rulesets.GetActiveAsync(workflowName);
    Assert.Equal(version, activeRuleset.Version);
}

Test Audit Trail

After activating a ruleset, verify audit entries were created:

[Fact]
public async Task RulesetLifecycle_CreatesAuditEntries()
{
    var client = new ControlPlaneApiClient("https://cp.example.com");
    var workflowName = "test-audit-" + Guid.NewGuid();

    // Save → approve → activate
    var ruleset = new { rules = new[] { /* ... */ } };
    var saveResp = await client.Rulesets.SaveAsync(workflowName, ruleset);
    await client.Rulesets.ApproveAsync(workflowName, saveResp.Version);
    await client.Rulesets.ActivateAsync(workflowName, saveResp.Version);

    // Fetch audit log
    var auditLog = await client.Audit.GetByWorkflowAsync(workflowName);

    Assert.NotEmpty(auditLog.Entries);
    Assert.Contains(auditLog.Entries, e => e.Action == "saved" && e.Version == saveResp.Version);
    Assert.Contains(auditLog.Entries, e => e.Action == "approved" && e.Version == saveResp.Version);
    Assert.Contains(auditLog.Entries, e => e.Action == "activated" && e.Version == saveResp.Version);
}

Test Maker-Checker Rejection

When maker-checker is enabled, verify that self-approval is rejected:

[Fact]
public async Task Approval_RejectsSelfApproval()
{
    var client = new ControlPlaneApiClient("https://cp.example.com");
    var workflowName = "test-maker-checker-" + Guid.NewGuid();

    var ruleset = new { rules = new[] { /* ... */ } };
    var saveResp = await client.Rulesets.SaveAsync(workflowName, ruleset);

    // Same user tries to approve their own submission
    await Assert.ThrowsAsync<UnauthorizedAccessException>(
        () => client.Rulesets.ApproveAsync(workflowName, saveResp.Version));
}

---

Decision Table Testing

Test decision tables: import, validate, export, and version comparison.

Import and Validate DMN

using Muonroi.ControlPlane.Sdk;
using Xunit;

[Fact]
public async Task DecisionTable_ImportAndValidate()
{
    var client = new ControlPlaneApiClient("https://cp.example.com");
    var dmnXml = @"
        <?xml version='1.0' encoding='UTF-8'?>
        <definitions xmlns='http://www.omg.org/spec/DMN/20151101/dmn.xsd'>
          <decisionTable id='dt_1'>
            <input id='input_1'><inputExpression typeRef='string'/></input>
            <output id='output_1' typeRef='string'/>
            <rule id='rule_1'>
              <inputEntry><text>'approved'</text></inputEntry>
              <outputEntry><text>'PASS'</text></outputEntry>
            </rule>
          </decisionTable>
        </definitions>";

    // Import DMN
    var tableId = Guid.NewGuid().ToString();
    var importResp = await client.DecisionTables.ImportDmnAsync(tableId, dmnXml);

    Assert.NotNull(importResp.Rows);
    Assert.Equal(1, importResp.Rows.Count);

    // Validate table
    var validateResp = await client.DecisionTables.ValidateAsync(tableId, importResp.Version);
    Assert.True(validateResp.IsValid);
    Assert.Empty(validateResp.Errors);
}

Evaluate Table with Test Input

[Fact]
public async Task DecisionTable_EvaluateWithInput()
{
    var client = new ControlPlaneApiClient("https://cp.example.com");
    var tableId = "test-table-id";

    var input = new { status = "approved", amount = 5000 };

    var result = await client.DecisionTables.EvaluateAsync(tableId, input);

    Assert.NotNull(result.Output);
    Assert.Equal("APPROVED", result.Output["decision"]);
}

Compare Version History

[Fact]
public async Task DecisionTable_CompareVersions()
{
    var client = new ControlPlaneApiClient("https://cp.example.com");
    var tableId = "test-table-id";

    var diff = await client.DecisionTables.DiffVersionsAsync(tableId, fromVersion: 1, toVersion: 2);

    Assert.NotNull(diff.Added);
    Assert.NotNull(diff.Removed);
    Assert.NotNull(diff.Modified);
}

---

Testing FEEL Expressions

Test FEEL evaluation via the /api/v1/feel/evaluate endpoint or directly via the expression evaluator.

Evaluate FEEL Expression via API

[Fact]
public async Task Feel_EvaluatesExpression()
{
    var client = new ControlPlaneApiClient("https://cp.example.com");

    var feelExpr = "amount > 1000 and status = 'approved'";
    var context = new { amount = 5000, status = "approved" };

    var result = await client.Feel.EvaluateAsync(feelExpr, context);

    Assert.True(result.Success);
    Assert.Equal(true, result.Value);
}

---

Testing Hot-Reload with SignalR

When EnableHotReload: true, verify that rule changes propagate via SignalR without requiring manual app restart.

Subscribe to Ruleset Changes

using Microsoft.AspNetCore.SignalR.Client;
using Xunit;

[Fact]
public async Task HotReload_RulesetChangeNotification()
{
    var connection = new HubConnectionBuilder()
        .WithUrl("https://cp.example.com/hubs/ruleset-changes")
        .WithAutomaticReconnect()
        .Build();

    var tcs = new TaskCompletionSource<string>();

    connection.On<string, int>("RulesetChanged", (workflow, version) =>
    {
        tcs.TrySetResult($"{workflow}:{version}");
    });

    await connection.StartAsync();

    // Trigger ruleset change via API
    var client = new ControlPlaneApiClient("https://cp.example.com");
    await client.Rulesets.ActivateAsync("my-workflow", 42);

    // Wait for SignalR notification
    var notification = await tcs.Task.ConfigureAwait(false);

    Assert.Equal("my-workflow:42", notification);
    await connection.StopAsync();
}

---

CI/CD Configuration

Running Tests in Pipeline

# GitHub Actions example
- name: Run Unit Tests
  run: dotnet test --filter "Category=Unit" --logger "trx" -v minimal

- name: Run Integration Tests
  run: dotnet test --filter "Category=Integration" --logger "trx" -v minimal
  env:
    DATABASE_CONNECTION: "postgres://..."
    REDIS_URL: "redis://..."

Test Categories

Apply [Trait("Category", "Unit")] to unit tests (no external dependencies):

[Fact]
[Trait("Category", "Unit")]
public async Task MyRule_ShouldWork()
{
    // Uses MRuleOrchestratorSpy, no DB
}

Apply [Trait("Category", "Integration")] to tests requiring database:

[Fact]
[Trait("Category", "Integration")]
public async Task RulesetLifecycle_SaveAndActivate()
{
    // Requires Postgres + Redis
}

---

Best Practices

1. Isolate contexts — use MRuleOrchestratorSpy for unit tests to avoid database setup.
2. Test failure paths — verify both success and failure cases (RuleResult.Failure).
3. Assert fact changes — inspect ExecutionRecords[i].Changes to verify what the rule modified.
4. Verify execution order — use ExecutionRecords to confirm dependency resolution worked correctly.
5. Test multi-tenant isolation — use keyed service registration to ensure tenant rules don't leak.
6. Integration tests separate — tag with [Trait("Category", "Integration")] and run in dedicated pipeline.
7. Mock external services — use Moq to mock HTTP clients, message queues, etc. in unit tests.

---

References

• Rule Engine Guide — architecture and concepts
• Decision Tables — DMN import and FEEL evaluation
• Control Plane API — ruleset CRUD and approval workflow