STD: Rules Engine Framework
Version: v1.0.1
Status: Draft
SRS Source: rules/rules.md
Rule Name: RULES ENGINE (Framework)
Domain: RULES-ENGINE
Overview
This document specifies tests for the Rules Engine framework using decision tables and test vectors. The Rules Engine is the infrastructure layer that governs all rule execution: which rules apply to a given analysis context (conditional execution), the sequence in which they execute (sequential ordering), and how errors and warnings affect analysis flow (error/warning flow control).
Rule Characteristics:
- Infrastructure layer (not an individual rule algorithm)
- Conditional execution based on Rules Mapping configuration
- Deterministic sequential execution by configured run order
- Error/warning flow control via
does_prevent_analyse flag (per-well: blocks further rule execution for affected well(s), not the entire pipeline)
- Implicitly exercised by every individual rule test, but requires explicit verification
Test Method: TM-API (per Test Plan Section 3.3 - Rules use automated API tests)
Verification Approach:
Rule verification is performed using data-driven test vectors. Each row in a decision table represents a complete verification scenario with defined inputs and expected outputs. This format enables exhaustive condition coverage while remaining concise and auditable.
Note: These three REQs are implicitly exercised by every rule test in the system -- any test that runs a rule through the analysis pipeline exercises mapping lookup, execution ordering, and error flow control. However, explicit verification is needed to confirm edge cases (e.g., empty mappings, duplicate run orders, mixed blocking/non-blocking error sequences) that individual rule tests do not isolate.
Coverage Summary
| REQ ID | Title | Conditions | Test Vectors | Coverage | Gaps | Automation Status |
|---|
| REQ-RULES-ENGINE-001 | Conditional Rule Execution Based on Mapping | 6 | 8 | 100% | None | Implicit (all rule tests exercise mapping) |
| REQ-RULES-ENGINE-002 | Sequential Rule Execution Order | 4 | 5 | 100% | None | Implicit (multi-rule tests exercise ordering) |
| REQ-RULES-ENGINE-003 | Error/Warning Flow Control | 6 | 8 | 100% | None | Implicit (error-producing rule tests exercise flow control) |
Totals: 3 REQs, 16 Conditions, 21 Test Vectors, 100% Coverage
| Variable | Type | Valid Values | Description |
|---|
rules_mapping[] | array | mapping entries | Rules Mapping sheet entries (Rule ID, Dye, Target Name, Mix, Sample Type) |
rule_setup[] | array | setup entries | Rule Setup sheet entries (Rule ID, run_order) |
error_codes[] | array | error code entries | Error Codes sheet entries (code, does_prevent_analyse) |
analysis.dye | string | FAM, HEX, ROX, ... | Dye for the current analysis context |
analysis.target_name | string | target identifier | Target Name for the current analysis context |
analysis.mix | string | Mix1, Mix2, ... | Mix for the current analysis context |
analysis.sample_type | string? | Serum, Plasma, ... | Sample Type for the current analysis context (when filtering enabled) |
config.sample_type_filtering_enabled | bool | true, false | Whether Sample Type filtering is active |
rule.result | string? | null, error_code | Result returned by an executed rule |
error.does_prevent_analyse | string | 'x', '' | Per-error-code flag: 'x' = blocking, '' = non-blocking |
Output Variables (Common)
| Variable | Type | Description |
|---|
rule.executed | bool | Whether a given rule was executed |
execution_order | array | Ordered list of rules that actually executed |
analysis.halted | bool | Whether analysis of the affected well(s) stopped before completing all rules (per-well; other wells continue through the pipeline normally) |
analysis.error_code | string? | Error/warning code returned from analysis |
analysis.error_message | string? | Error/warning message returned from analysis |
REQ-RULES-ENGINE-001: Conditional Rule Execution Based on Mapping
Acceptance Criteria Mapping
| AC ID | Acceptance Criterion | Test Vectors |
|---|
| AC-001-1 | Execute rule when mapping matches Dye, Target Name, and Mix | TV-ENGINE-001-001 |
| AC-001-2 | Skip rule when no mapping matches current context | TV-ENGINE-001-002, TV-ENGINE-001-003 |
| AC-001-3 | Evaluate mappings before attempting rule execution | TV-ENGINE-001-002 |
| AC-001-4 | When Sample Type filtering enabled, require Sample Type match | TV-ENGINE-001-005, TV-ENGINE-001-006 |
| AC-001-5 | When Sample Type filtering disabled, evaluate only Dye, Target Name, Mix | TV-ENGINE-001-004 |
| AC-001-6 | No rules mapped: complete analysis without executing any rules | TV-ENGINE-001-007 |
Decision Table: Rule Mapping Match
Tests whether a rule executes based on the presence and match of a Rules Mapping entry for the current analysis context.
| TV | mapping.dye | mapping.target | mapping.mix | analysis.dye | analysis.target | analysis.mix | rule.executed | Covers |
|---|
| TV-ENGINE-001-001 | FAM | COVID | Mix1 | FAM | COVID | Mix1 | true | AC: Valid mapping exists, rule executes |
| TV-ENGINE-001-002 | FAM | COVID | Mix1 | HEX | COVID | Mix1 | false | AC: Dye mismatch, rule skipped (no error, no output) |
| TV-ENGINE-001-003 | FAM | COVID | Mix1 | FAM | HEV | Mix2 | false | AC: Target and Mix mismatch, rule skipped |
Decision Table: Multiple Rules with Selective Mapping
Tests that only rules with valid mappings execute when multiple rules are configured.
| TV | rules_configured | rules_mapped_to_context | rules_executed | Covers |
|---|
| TV-ENGINE-001-004 | RuleA, RuleB, RuleC | RuleA, RuleC | RuleA, RuleC | AC: Only mapped rules execute; RuleB skipped |
Decision Table: Sample Type Filtering
Tests that Sample Type filtering correctly gates rule execution when enabled.
| TV | sample_type_filtering | mapping.sample_type | analysis.sample_type | mapping_matches | rule.executed | Covers |
|---|
| TV-ENGINE-001-005 | enabled | Serum | Serum | true | true | AC: Sample Type matches, rule executes |
| TV-ENGINE-001-006 | enabled | Serum | Plasma | false | false | AC: Sample Type mismatch, rule skipped |
Decision Table: Empty Rules Mapping
Tests that analysis completes gracefully when no rules are mapped.
| TV | rules_mapping | rules_executed | analysis.halted | analysis.error_code | Covers |
|---|
| TV-ENGINE-001-007 | [] (empty) | none | false | null | AC: No rules mapped, analysis completes without error |
| TV-ENGINE-001-008 | unavailable | n/a | true | CONFIGURATION_ERROR | EH: Rules Mapping unavailable, analysis halted |
REQ-RULES-ENGINE-002: Sequential Rule Execution Order
Acceptance Criteria Mapping
| AC ID | Acceptance Criterion | Test Vectors |
|---|
| AC-002-1 | Execute rules in ascending order by run_order value | TV-ENGINE-002-001 |
| AC-002-2 | Rule with order N completes before rule with order > N begins | TV-ENGINE-002-001 |
| AC-002-3 | Execution sequence is deterministic for a given configuration | TV-ENGINE-002-002 |
| AC-002-4 | Modified run_order changes execution sequence | TV-ENGINE-002-004 |
Decision Table: Execution Order
Tests that rules execute in the correct ascending order based on run_order configuration.
| TV | RuleA.run_order | RuleB.run_order | RuleC.run_order | expected_execution_order | Covers |
|---|
| TV-ENGINE-002-001 | 10 | 5 | 15 | RuleB, RuleA, RuleC | AC: Ascending order by run_order |
| TV-ENGINE-002-002 | 10 | 10 | 20 | {RuleA,RuleB} (implementation-defined), RuleC | AC: Duplicate run_order, deterministic but implementation-defined |
Decision Table: Order-Dependent Output
Tests that rule ordering affects analysis output when rules have data dependencies.
| TV | RuleA (run_order=5) | RuleB (run_order=10) | dependency | result_correct | Covers |
|---|
| TV-ENGINE-002-003 | Produces intermediate value X | Consumes value X | B depends on A | true | AC: Correct order produces correct result |
Decision Table: Modified Run Order
Tests that changing run_order in configuration changes the actual execution sequence.
| TV | initial_order (A=5, B=10) | modified_order (A=15, B=10) | initial_sequence | modified_sequence | Covers |
|---|
| TV-ENGINE-002-004 | A=5, B=10 | A=15, B=10 | A, B | B, A | AC: Config change alters execution order |
Decision Table: Configuration Unavailable
| TV | rule_setup | analysis.halted | analysis.error_code | Covers |
|---|
| TV-ENGINE-002-005 | unavailable | true | CONFIGURATION_ERROR | EH: Rule Setup unavailable, analysis halted |
REQ-RULES-ENGINE-003: Error/Warning Flow Control
Per-well scope: The does_prevent_analyse flag operates at the well level, not the pipeline level. When a rule produces a blocking error for a well, that well is excluded from further rule evaluation, but the analysis pipeline continues processing all other wells normally. "Halts analysis" and "stops execution" in this section refer to halting further rule execution for the affected well(s) only.
Acceptance Criteria Mapping
| AC ID | Acceptance Criterion | Test Vectors |
|---|
| AC-003-1 | Blocking error (does_prevent_analyse = 'x') prevents further rule execution for the affected well(s) | TV-ENGINE-003-001 |
| AC-003-2 | Non-blocking error (does_prevent_analyse = '') allows continued rule execution for the well | TV-ENGINE-003-002 |
| AC-003-3 | First blocking error prevents further rule execution for the well; subsequent rules do not run for that well | TV-ENGINE-003-003 |
| AC-003-4 | Non-blocking followed by blocking: first runs, second blocks further execution for the well, third skipped for that well | TV-ENGINE-003-004 |
| AC-003-5 | All non-blocking: all rules execute for the well; first non-blocking error returned | TV-ENGINE-003-005 |
| AC-003-6 | does_prevent_analyse config flag toggled changes behavior | TV-ENGINE-003-006 |
Decision Table: Blocking Error Prevents Further Rule Execution for Well
Tests that a rule returning a blocking error (does_prevent_analyse = 'x') prevents subsequent rule execution for the affected well(s).
| TV | RuleA.error | A.does_prevent_analyse | RuleB.mapped | RuleB.executed | analysis.halted | analysis.error_code | Covers |
|---|
| TV-ENGINE-003-001 | E001 | 'x' (true) | true | false | true | E001 | AC: Blocking error prevents further rule execution for the well; RuleB does not execute |
Decision Table: Non-Blocking Error Allows Continuation
Tests that a rule returning a non-blocking error (does_prevent_analyse = '') allows subsequent rules to execute.
| TV | RuleA.error | A.does_prevent_analyse | RuleB.executed | RuleB.error | analysis.halted | analysis.error_code | Covers |
|---|
| TV-ENGINE-003-002 | E002 | '' (false) | true | null | false | E002 | AC: Non-blocking error, RuleB executes, E002 returned |
Decision Table: Multiple Blocking Errors
Tests that the first blocking error prevents further rule execution for the well and is the one returned.
| TV | RuleA.error | A.does_prevent | RuleB.error | B.does_prevent | RuleB.executed | analysis.error_code | Covers |
|---|
| TV-ENGINE-003-003 | E001 | 'x' (true) | E003 | 'x' (true) | false | E001 | AC: First blocking error prevents further execution for the well; RuleB never runs |
Decision Table: Mixed Blocking and Non-Blocking Sequence
Tests a sequence of non-blocking then blocking errors.
| TV | RuleA (order=1) | A.does_prevent | RuleB (order=2) | B.does_prevent | RuleC (order=3) | C.executed | analysis.error_code | Covers |
|---|
| TV-ENGINE-003-004 | E002 (warning) | '' (false) | E001 (error) | 'x' (true) | n/a | false | E001 | AC: A runs (non-blocking), B blocks further execution for the well (blocking), C skipped |
Decision Table: All Non-Blocking Errors
Tests that when all errors are non-blocking, all rules execute and the first error is returned.
| TV | RuleA.error | A.does_prevent | RuleB.error | B.does_prevent | RuleC.error | C.does_prevent | all_executed | analysis.error_code | Covers |
|---|
| TV-ENGINE-003-005 | E002 | '' (false) | E003 | '' (false) | null | n/a | true | E002 | AC: All rules execute; first non-blocking error (E002) returned |
Decision Table: Config Flag Toggle
Tests that changing the does_prevent_analyse flag alters flow control behavior for the same error code.
| TV | error_code | does_prevent_analyse (before) | behavior_before | does_prevent_analyse (after) | behavior_after | Covers |
|---|
| TV-ENGINE-003-006 | E002 | '' (false) | continues | 'x' (true) | blocks further execution for the well | AC: Toggling flag changes blocking behavior |
Decision Table: Unknown Error Code / Config Unavailable
| TV | error_code | error_codes_config | does_prevent_analyse | analysis.halted | Covers |
|---|
| TV-ENGINE-003-007 | E999 | E999 not in config | treated as blocking | true | EH: Unknown error code treated as blocking |
| TV-ENGINE-003-008 | any | unavailable | n/a | true | EH: Error Codes config unavailable, analysis halted |
Traceability to Existing Tests
| Requirement | Jira Tests | Automation Status |
|---|
| REQ-RULES-ENGINE-001 | Implicitly by all rule BT tests | Implicit -- every rule test exercises mapping lookup |
| REQ-RULES-ENGINE-002 | Implicitly by multi-rule BT tests | Implicit -- multi-rule configs exercise ordering |
| REQ-RULES-ENGINE-003 | Implicitly by error-producing rule tests | Implicit -- blocking/non-blocking behavior exercised in rule tests |
Note: No dedicated BT tickets exist for explicit Rules Engine framework verification. All existing rule tests (e.g., BT-5134, BT-5172, BT-5221, etc.) implicitly exercise the engine but do not isolate the framework behaviors specified in REQ-RULES-ENGINE-001 through 003. Explicit test cases should be created to verify edge cases such as empty mappings, duplicate run orders, and mixed error flow sequences.
Gap Analysis
Identified Gaps
| Gap | Requirement | Description | Priority |
|---|
| GAP-001 | REQ-RULES-ENGINE-001 | No explicit test for empty Rules Mapping (TV-ENGINE-001-007) or config unavailable (TV-ENGINE-001-008) | Medium |
| GAP-002 | REQ-RULES-ENGINE-002 | No explicit test isolating run_order sequencing independent of individual rule logic | Medium |
| GAP-003 | REQ-RULES-ENGINE-003 | No explicit test for mixed blocking/non-blocking error sequences (TV-ENGINE-003-004, TV-ENGINE-003-005) | Medium |
| GAP-004 | REQ-RULES-ENGINE-003 | No explicit test for unknown error code handling (TV-ENGINE-003-007) | Low |
- GAP-001 (Empty/Missing Mapping): Create a config variant with an empty Rules Mapping sheet and verify analysis completes with no rule execution. Create a second variant with a corrupt/missing Rules Mapping to verify configuration error handling.
- GAP-002 (Execution Order): Create a multi-rule config where two rules with different run_order values produce order-dependent output, verifying the lower-ordered rule executes first.
- GAP-003 (Mixed Error Flow): Create a config with at least three rules where the first produces a non-blocking warning, the second produces a blocking error, and verify the third does not execute.
- GAP-004 (Unknown Error Code): Create a rule that returns an error code not present in the Error Codes configuration and verify analysis halts (treated as blocking).