Home / admin / uat-test-case-design

uat-test-case-design

Use this skill when designing the human-executable UAT test cases that prove a Salesforce feature works for a specific persona — the per-persona scripts with preconditions, data setup, permission setup, ordered steps, and pass/fail evidence that close out an RTM row.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Reliability
• Operational Excellence
• User Experience

• uat
• test-case
• testing
• business-analysis
• traceability

Open the skill folder on GitHub

UAT Test Case Design

This skill activates when a Business Analyst, QA lead, or admin needs to convert acceptance criteria into the per-persona, human-executable UAT scripts that prove a Salesforce feature works in the UI. It is the script-authoring layer beneath the broader UAT plan — it does not own sign-off, defect taxonomy, or regression strategy.

Before Starting

Gather this context before writing a single case:

• Is the AC block testable? Cases derive 1-to-1 (or 1-to-N) from acceptance criteria scenarios. If the AC is vague ("the page should be intuitive"), stop and route the work back to admin/acceptance-criteria-given-when-then before authoring scripts.
• Who is the persona? A UAT case is meaningless without a persona. Capture the profile + permission set group the tester will be assigned. Never test as System Administrator — that posture invalidates the FLS, sharing, and CRUD checks the case is supposed to prove.
• What sandbox is the build deployed in? Cases must reference the sandbox by name. A case that ran in a developer sandbox with no production-like data is not the same evidence as a case run in a Full sandbox.
• What data state is required? A case that fails because a parent Account did not exist is a setup failure, not a feature failure. Data setup must be explicit before the steps begin.
• Is there a negative path? Every story needs at least one UAT case that proves the feature blocks the wrong action — invalid input, wrong persona, missing required field. Happy-path-only UAT lets P1 security and validation defects through.

Questions to Ask Before Configuring

Put these to the BA, the QA lead and the release manager before writing a step. Each one closes a gotcha in references/gotchas.md; an LLM that skips them produces a script that reads well and proves nothing.

What a proper configuration adds over just writing the steps: every step carries its own expected result so a failure names the step that broke, every pass carries evidence that survives the next sandbox refresh, every deny is attributable to a named mechanism, and each case records whether it should stay manual — so the script set shrinks over releases instead of growing.

Core Concepts

The Canonical UAT Case Schema

A UAT test case is a structured artifact, not a paragraph. The canonical schema this skill enforces:

The first ten fields are authored before execution. The last five are filled at run time and become the evidence row that closes an RTM cell.

One AC Scenario → One UAT Case (or More)

A common failure mode is "one case per click" or "one case per story." Both miss the AC granularity. The correct decomposition:

1. Each AC scenario (Given/When/Then block) maps to at least one UAT case.
2. If the AC scenario applies to multiple personas with different expected outcomes, split into one case per persona.
3. If the AC scenario has multiple boundary values (e.g. credit limit at 0, at threshold, at threshold+1), split into one case per boundary.

This guarantees the UAT cases collectively prove every AC, which is the contract the RTM relies on.

Data Setup Discipline

The case body must not silently assume records exist. If the case requires "an Account with Type = Customer and credit limit > 50000," that requirement lives in the data_setup array. Two acceptable seeding approaches:

• Manual UI seed — for small, story-specific records the tester creates in the sandbox before running steps.
• Apex factory seed — for bulk or relationship-heavy seeds, reference templates/apex/tests/TestDataFactory.cls and invoke from anonymous Apex. UAT cases that depend on >5 records per run should use the factory.

Never seed in production. UAT runs in a sandbox.

Permission Setup Discipline

The single largest UAT antipattern is testing as System Administrator. The Sys Admin profile bypasses FLS, sharing rules, validation behavior tied to permissions, and most CRUD restrictions. A case that passes as Sys Admin proves nothing about the persona.

Permission setup rules:

1. The tester user runs with the persona's standard profile (often a Minimum Access / read-only baseline) plus the PSG that grants the feature.
2. The PSG to assign is named explicitly in permission_setup — not "the right perms," not "the dev's profile."
3. If the feature is gated by a permission set (not a PSG), the case must still cite that permission set.
4. If the case's intent is to prove the feature is denied to a persona, the persona is set up without the PSG and the expected_result is the deny.

Negative-Path Coverage

Every story needs at least one case where negative_path: true. Examples:

• Required field omitted → save fails with the validation rule's error message
• Wrong persona attempts the action → permission error, not silent success
• Boundary value just past the limit → block, not allow
• Stage skip (e.g. Closed Won without a Close Date) → validation rejects

Without a negative-path case, the UAT run only proves the feature works when used correctly. It does not prove the feature is safe.

Common Patterns

Pattern: Decompose an AC Block into UAT Cases

When to use: A story arrives with a Given/When/Then AC block from admin/acceptance-criteria-given-when-then. You need the UAT scripts.

How it works:

1. Read each Scenario: in the AC block. Each scenario produces ≥1 case.
2. For each scenario, identify which personas it applies to. Split per persona where outcomes differ.
3. Capture the persona's PSG into permission_setup. If the persona name is "Sales Rep — Pipeline Edition," the PSG is the one named in the security model, not "Sales Profile."
4. Translate the Given clause into precondition + data_setup. Records are seeded; user state is precondition.
5. Translate the When clause into ordered steps at click-level detail.
6. Copy the Then clause verbatim into expected_result.
7. Add negative_path: true cases for the AC's failure scenarios. Most AC blocks have at least one — extract them, do not invent new ones.

Why not the alternative: Writing cases freehand from the story description (without the AC block) drifts from what was contracted. Cases must be evidence that the AC was met, not evidence that "something works."

Pattern: UAT Case for a Bulk Data Loader Run

When to use: The feature under test is a data import, dedupe rule, or matching rule, executed via Data Loader rather than the standard UI.

How it works:

1. Treat the Data Loader run as a UI action — the persona is the user running Data Loader, not the integration user.
2. data_setup includes the source CSV file with row counts and the field mapping.
3. permission_setup includes the PSG that grants the API + Bulk API permissions to the loader user, plus object CRUD on the target.
4. Steps include the loader configuration: object, operation, mapping file, batch size.
5. expected_result covers both the success count and the failure count (e.g. "47 inserted, 3 rejected by duplicate rule").
6. Negative-path companion case: load a CSV with a known duplicate to prove the dup rule fires.

Pattern: UAT Case for a Lightning Record Page

When to use: The feature is a Lightning page layout change for a specific record type + persona combination.

How it works:

1. The persona's PSG controls the page-layout assignment indirectly via the profile + record type matrix. permission_setup cites both.
2. precondition names the exact record type and the record ID (or seeds one).
3. Steps walk through render, edit, sharing visibility, and any quick action present on the page.
4. Expected_result names every field/section that should be visible — not "page renders correctly."

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Intake the criteria, the personas and the environment. Confirm the AC block is in Given/When/Then form (per admin/acceptance-criteria-given-when-then) and that each persona resolves to a named profile plus a named grant. Take the sandbox, refresh date and persona roster from the programme file rather than re-deciding them — admin/uat-and-acceptance-criteria owns those. Answer ## Questions to Ask Before Configuring and record the answers in templates/uat-test-case-design-template.md.
2. Decompose criteria into cases. Each AC scenario → ≥1 case; split per persona and per boundary where the expected result diverges; keep every ac_id and req_id on the row. Work from the shape in references/worked-examples.md § 3, which does this for thirteen criteria.
3. Write the steps with a per-step expected result. Copy the skeleton from templates/uat-case.md. Every numbered step gets its own observable outcome — a field value, a query row, a file row, a message. A step whose expected result is "the page looks right" goes back to step 1's question about oracles.
4. Pin setup: data, permission, form factor. Enumerate data_setup in order (for >5 related records, cite templates/apex/tests/TestDataFactory.cls). Name the grant in permission_setup and gate the run on PermissionSetGroup.Status = 'Updated'. State the form factor in precondition. For deny cases, name what the persona is set up without.
5. Assign evidence and an automation verdict per case. Each case declares what closes it (screenshot / SOQL / email log / loader CSV / history row) and one of apex, flow-test, none with the reason — see references/worked-examples.md § 8 for the platform fact behind each verdict.
6. Lint the set before anyone runs it. python3 scripts/check_uat_case.py --manifest-dir ./uat/ — it fails on a step with no expected result, an ac_id that resolves to no criterion in the folder, a duplicate or malformed id, an ambiguous expected result, an automation verdict outside the enum, and a run-sheet row pointing at a case that does not exist.
7. Execute, then close the RTM cell. Testers add run-sheet rows (never edit an old one), set result from {Pass, Fail, Blocked, Not Run} and attach evidence. Re-run the gate with --rtm-gate, then write case_id + result + evidence into the RTM row keyed by req_id + ac_id per admin/requirements-traceability-matrix § 3.

Review Checklist

Run through these before declaring the case set ready for execution:

• [ ] Every case has story_id, ac_id, and a named persona (not "Admin")
• [ ] Every story has at least one case with negative_path: true
• [ ] Every case has a non-empty data_setup array (or an explicit "no setup needed" note if truly stateless)
• [ ] Every case has a non-empty permission_setup array citing the PSG by name
• [ ] Every case has ≥2 steps
• [ ] Every case's expected_result quotes the AC's then clause verbatim
• [ ] Every AC scenario in the source story is covered by ≥1 case
• [ ] No case lists "System Administrator" as persona
• [ ] Sandbox name is captured at the script-set level
• [ ] pass_fail values use the enum {Pass, Fail, Blocked, Not Run} only
• [ ] Every numbered step has its own expected result — none reads "verify it looks correct"
• [ ] Every case declares its evidence type and an automation_candidate of apex, flow-test or none
• [ ] Every deny case names what the persona is set up without, and rules out a scoping or restriction rule as the cause
• [ ] The precondition names the form factor the persona uses
• [ ] python3 scripts/check_uat_case.py --manifest-dir <folder> exits 0

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Page-layout assignment is profile + record type, not PSG. Adding a permission set to a tester does NOT change which page layout they see. Permission setup that ignores the page layout matrix produces cases that pass for the wrong reason. Confirm the tester's profile + record type combination is mapped to the right layout in Setup before the run.
2. An API load skips the layout half of validation, not the custom rules. Custom validation rules run for every request source at step 5 of the save order, so a Data Loader insert fires them too. What only runs "for requests from a standard UI edit page" is the step-2 set: compliance with layout-specific rules and required values at the layout level. A UI case therefore proves both halves; a loader case proves one. Write the loader case anyway — it is the half where a layout-required field silently loads blank.
3. Permission set group recalculation has a queryable status, not a waiting period. PermissionSetGroup.Status reads Updated, Outdated, Updating or Failed. A case that runs while the group is Outdated fails for setup reasons. Gate the run on the status query rather than on a guessed delay.

Output Artifacts

Official Sources Used

See references/well-architected.md § Official Sources Used for the guides and repo standards backing the permission, save-order, sandbox, and metadata claims in this package. Per-claim line citations sit beside the claims themselves in references/worked-examples.md and references/gotchas.md.

Reference Files

Related Skills

• admin/uat-and-acceptance-criteria — high-level UAT plan, environment rationale, persona roster, defect classification, regression strategy, sign-off. Activates around this skill, not under it.
• admin/acceptance-criteria-given-when-then — the technique that produces the AC block this skill consumes. Always run that skill first.
• admin/requirements-traceability-matrix — the matrix this skill's results close, and the owner of the REQ- / test_id id spaces.
• admin/sandbox-strategy — sandbox type, capacity and refresh floor; a case cites the sandbox but does not choose it.
• devops/sandbox-data-isolation-gotchas — deliverability, .invalid email scrubbing and CronTrigger carry-over, all of which decide whether a case is runnable at all.
• templates/apex/tests/TestDataFactory.cls — canonical factory referenced from data_setup when manual seeding is too slow.
• agents/test-class-generator/AGENT.md — generates Apex test methods. Distinct from this skill — these are human UI scripts; this skill only records which cases should become Apex tests.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• references/worked-examples.md
• templates/uat-case.md
• templates/uat-test-case-design-template.md
• scripts/check_uat_case.py
• scripts/check_uat_test_case_design.py