rules-rule-test-unit-case

Imported from pegasystems/infinity-ai-plugins (plugins/pega/infinity-ai-plugins/codex/resources/27-1/skills/rules-rule-test-unit-case/SKILL.md). Install upstream with npx skills add pegasystems/infinity-ai-plugins --skill rules-rule-test-unit-case. Copyright stays with the author.

Prerequisite: Load methodology-rule-authoring first

Purpose: The purpose of this rule is to test other rules.

Best practices

Attempt to, as much as possible, to cover as much of the code as possible with a single test. If multiple tests are needed, as often is the case, include some indication in the rule name how this is different from other tests. Examples: TC_RuleName_HappyPath or TC_RuleName_MissingParameter

Composability

Test cases are composed from three independent building blocks. Mix and match freely:

1. Assertion patterns (Assertion-level examples) — how to check a specific condition (Property, Decision, List, etc.). These work the same regardless of rule-under-test type.
2. Rule-under-test blocks (Rule-under-test examples) — how to target a specific rule type (Activity, Data Transform, Decision Table, etc.). These are independent of assertion choice.
3. Setup pages (Setup pages examples) — how to pre-load clipboard state before the test runs. These are RUT-type-agnostic.
4. Test infrastructure — setup/cleanup activities, pages-and-classes, and RUT parameters. These are RUT-type-agnostic.

To build a test case: pick the assertion(s) from Assertion-level, the RUT block from Rule-under-test, and optionally add setup/cleanup. The Rule-level examples show complete compositions for the most common patterns.

RUT type to available assertion types

Bold = not available for all RUT types. Property, Page, List, ResultCount, and ExpectedRuntime are available for all RUT types. Decision is available for DecisionTable, DecisionTree, Expressions, and When rules. ActivityStatus is exclusive to activities.

Examples

Rule-level

Assertion-level

Setup pages

Rule-under-test

Authoring notes

Test data cleanup

Important: Always set pyCleanUpTestData: "true" explicitly when creating test cases for Constellation apps (Pega 8.4+). This field is not auto-filled by the builder. Omitting it may result in test data persisting after test execution. For pre-8.4 traditional apps, omit this field or set it to "false".

pyPurpose is the class key

pyPurpose (with pyClassName) is the identity key (from pyKeyDefList) and the value the agent must supply. pyRefToFocusKey and pyClassContext are auto-derived from pyPurpose and pyClassName respectively and can be omitted.

• pyExpectedValue quoting depends on assertion type and pyPropertyMode. For Property assertions: Text, Date, and DateTime values must be wrapped in escaped inner quotes ("\"my text\"", "\"20200520T091028.850 GMT\"" for DateTime). DateTime uses Pega's internal format yyyyMMddTHHmmss.SSS GMT, NOT ISO 8601. Numeric and TrueFalse values must NOT use inner quotes. For Decision assertions: all pyExpectedValue values are bare strings without inner quotes (e.g., "High", "true", "100", "Incomplete"). See the schema description on pyExpectedValue for the full rule.
• pyExpectedResults is reused at two levels — do not confuse them. The top-level pyExpectedResults array holds assertion groups (ActivityStatus, Property, Decision, etc.). Inside a Property assertion group, the same field name pyExpectedResults holds the nested array of individual property checks. The field is always pyExpectedResults at both levels — there is no pyExpectedResultsList or other variant. See Property Assertion or Property Assertion on a Custom Page for the two-level Property pattern.
• pyPropertyMode casing differs by assertion type. Property assertions use Title Case (Text, TrueFalse, Identifier). Decision assertions use lowercase (decimal, text).
• pyComparator casing is irregular. Use exact values from the schema enum (e.g., IS Not Equals TO has mixed caps). The schema includes x-pega-hints to correct common casing mistakes.
• Exists comparator does not work inside List assertions. When checking that a property is present and non-empty on list items (e.g., .pxResults), use "pyComparator": "IS Not Equals TO" with "pyExpectedValue": "\"\"" instead of "pyComparator": "Exists". The Exists comparator silently fails in the List assertion context — the test reports empty Actual and Expected values with no error. Exists works in Property assertions but not when nested inside a List assertion's pyExpectedResults.
• Setup/cleanup activities (pySetup/pyCleanup) run before/after the test. Parameters go in pySetupParams as comma-separated key=value pairs and in pyParametersDetails as structured entries. Use "None" for no parameters. See Report Definition Test (Complex Test with Setup/Cleanup) for a complete example.
• RUT parameters (pyRuleUnderTest.pyParameters) pass input to the rule under test. String values need escaped inner quotes in pyParametersParamValue.
• Pages and classes (pyPagesAndClasses) declare named clipboard pages and their classes. Required when the test uses custom page names (e.g., for Property, List, or Page assertions on non-default pages).
• Decision tables with parameter columns. When the decision table under test declares its columns as parameters (e.g. param.Locale) rather than case properties, the assertion engine and the Manage Properties refresh action in Dev Studio both match input rows by column identifier. The param.<Name> token must therefore appear verbatim in pyDisplayLabel, pyPropertyName, and pyPropertyAbsolutePath. Friendly labels (pyDisplayLabel: "Locale") save successfully but cause the Manage Properties refresh to drop or duplicate the input rows because Pega cannot reconcile the labels back to the parameter columns. Use the lowercase param. prefix -- that is the form Dev Studio persists when authoring by hand and the form that round-trips cleanly. Mixed-case variants (param.Locale) have not been verified to round-trip. Each branch row must also carry a concrete pyExpectedValue on the input rows; omitting it sends an empty string and silently masks coverage of every non-default branch (only the default-fallback row should leave inputs empty). See Decision Table Test with Parameter Inputs. Property-backed decision tables (Decision Assertion Test) keep using friendly display labels -- the two patterns differ only in the input rows.
• Decision assertion pyPropertyMode enum is narrow. The schema only accepts text, decimal, date (lowercase) -- there is no truefalse, integer, or datetime mode for Decision assertions, even when the decision table column itself is one of those types. For boolean parameter columns (truefalse), use pyPropertyMode: "text" with pyExpectedValue of "true" / "false". Numeric pyExpectedValue strings carry no inner quotes (same convention as the Result row). Mismatched modes can silently degrade to string comparison.
• Multi-row Decision assertions. A single Decision assertion can hold many test rows -- one per pyExpectedResults entry inside the Decision Result group. Give each row a unique pyPageName (e.g. row_premium_zero, row_default) and repeat the input/result triple inside each. The Result row keeps the literal label "Result" -- that is the fixed identifier the Decision assertion uses for the decision table's return value, regardless of whether the inputs are properties or parameters. pyPagesAndClasses is not required for parameter inputs (no clipboard page is referenced).
• Property assertion page targeting. pyStepPageName and pyPageName in a Property assertion must match the clipboard page where the rule-under-test writes the property — they are NOT always RunRecordPrimaryPage. Before writing assertions, read the rule under test (via get-rule) and trace which page each property is set on. For example, if an activity uses Page-New to create a page called test and then Property-Set sets .pyLabel on that page, the Property assertion must use "pyStepPageName": "test" and "pyPageName": "test", and the page must be declared in pyPagesAndClasses. Use RunRecordPrimaryPage only when the rule operates on its primary page. See Property Assertion on a Custom Page for the complete pattern.
• Connector-backed Data Page assertions. ResultCount assertions work reliably against connector-backed (live external API) list Data Pages. Nested List assertions checking specific pxResults(N) property values are fragile against connector-backed sources — an assertion structured identically to a working local-Data-Page pattern can fail even when the underlying data is independently confirmed correct via run-data-page. Root cause not fully determined. Prefer a ResultCount assertion on the list Data Page, plus a separate single-record lookup Data Page test asserting specific property values there, over nested list-item assertions on the connector-backed list Data Page. See Data Page Test (Connector-Backed List).

Test failure triage

When a test fails after modifying a rule, determine the cause before fixing:

Re-run tests after every fix. Do not batch multiple fixes before re-running — the feedback loop's value comes from immediate verification.