Omnistudio Testing Patterns

OmniStudio Testing Patterns

This skill activates when a practitioner needs to test, validate, or debug OmniStudio components — OmniScripts, Integration Procedures, or DataRaptors — before or after deployment. It covers the three built-in manual test surfaces Salesforce provides, their known gaps, and what end-to-end automated testing actually requires.

Before Starting

Gather this context before working on anything in this domain:

• Runtime type matters: Determine whether the org uses Package Runtime (managed package, OmniStudio namespace) or Standard/Core Runtime (native metadata). UTAM automation targets differ between the two because HTML rendering differs across runtimes.
• Most common wrong assumption: Practitioners treat OmniScript Preview mode as a full simulation. It is not — Preview always runs in the admin user security context, silently skips Navigation Actions, and does not exercise Named Credentials or Experience Cloud guest-user permissions. A passing Preview does not mean the component works for end users.
• No first-party automated test framework exists: Salesforce does not ship a built-in automated testing library for OmniStudio. End-to-end automation requires UTAM (UI Test Automation Model), Selenium, or equivalent browser automation tools applied against a deployed runtime.

Core Concepts

OmniScript Preview Mode

OmniScript Preview is an in-designer tool accessible from the OmniScript designer canvas. It renders the script using the designer's admin security context — not the target user's context — and skips Navigation Actions (Save/Navigate steps). It validates JSON structure, conditional rendering logic, and basic step sequencing, but it cannot test permission-controlled data access, FLS-gated fields, or Experience Cloud guest-user behavior. Preview is mandatory as a first-pass gate but must never be treated as final sign-off.

Integration Procedure Test Execution

Integration Procedure (IP) designers include a per-step test execution panel that accepts a JSON input payload and returns the full step response including vlcStatus (success/error/warning), errorMessage, responseSize, and step timing. Each step can be tested in isolation by providing mock input — this allows identification of which step in a multi-step IP is failing without deploying and running the full chain. Named Credentials are evaluated at test execution time, making this the correct tool for testing IP callouts — but it still runs as the admin user.

DataRaptor Preview

DataRaptor Extract, Transform, and Load components all have a Preview/Test tab in their designer. Extract Preview accepts a record ID and returns field-mapped output; Transform Preview accepts a JSON input and shows the transformed output; Load Preview simulates a write operation. These are essential for validating field mapping formulas before wiring a DataRaptor into an Integration Procedure or OmniScript. DataRaptor Preview uses the admin context like the other tools.

UTAM and Browser Automation

UTAM (UI Test Automation Model) is Salesforce's open-source framework for describing UI component interactions in a JSON page-object format that compiles into Selenium WebDriver commands. For OmniStudio, UTAM page objects exist for the runtime components (OmniScript elements, step navigation, submit actions). End-to-end testing with UTAM runs against a fully deployed org in the target user's security context, making it the only approach that catches permission gaps and Navigation Action behavior. UTAM page objects for managed-package HTML differ from Standard Runtime HTML — use the correct page object library for the org's runtime.

Common Patterns

Layered Three-Stage Testing

When to use: Any OmniScript with Integration Procedure callouts, multiple steps, and role-based conditional fields targeting non-admin users (e.g., Experience Cloud guests, community users with restricted profiles).

How it works:

1. Run DataRaptor Preview for each DataRaptor in the chain to confirm field mappings produce expected output.
2. Run Integration Procedure Test Execution step-by-step with a representative JSON payload. Confirm each step's vlcStatus is success and review timing for any step exceeding 5 seconds.
3. Run OmniScript Preview to validate conditional rendering, step-to-step navigation logic, and formula expressions.
4. Deploy to a scratch org or sandbox and run a UTAM-based or manual walkthrough as the actual target user (e.g., create a community guest test session or login-as the relevant profile).

Why not Preview alone: Preview always runs as admin, skips Navigation Actions, and does not test Named Credentials in the real user context. Skipping step 4 is the most common production defect path.

Integration Procedure Step-Isolation Debugging

When to use: An IP is failing in production or staging and the error message from the OmniScript output is vague (e.g., "Integration Procedure Error" without step detail).

How it works:

1. Open the IP designer and navigate to the failing step's Test tab.
2. Construct a JSON input object representing the values that would flow into that step from prior steps. Use prior step outputs from a known-good run if available.
3. Execute the step and inspect the response JSON: vlcStatus of error with a populated errorMessage pinpoints the failure; warning status may continue execution but silently produce partial data.
4. If the step calls a Named Credential, confirm the credential is active and the integration user has access.
5. Fix at the step level and re-run the IP end-to-end before re-deploying.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Identify the component type and runtime — Determine whether the failing or to-be-tested component is an OmniScript, Integration Procedure, or DataRaptor, and whether the org uses Package Runtime or Standard/Core Runtime. This determines which test tool applies and which UTAM page objects to use.
2. Run DataRaptor Preview for all DataRaptors in the chain — Open each DataRaptor in the designer, navigate to the Preview/Test tab, supply a representative record ID or JSON payload, and confirm field mappings produce expected output. Fix any mapping errors before proceeding.
3. Run IP Test Execution step-by-step — For each Integration Procedure step, open the Test tab, supply the JSON input that would reach that step from prior steps, execute, and inspect vlcStatus, errorMessage, and timing. Resolve any step with a non-success status before testing the full IP end-to-end.
4. Run OmniScript Preview — Execute OmniScript Preview in the designer. Validate conditional rendering, required field logic, step navigation expressions, and formula outputs. Document any step that relies on Navigation Actions or user-context data — these cannot be validated in Preview.
5. Deploy to sandbox and test as target user — Deploy the component to a sandbox. Log in as (or use login-as for) a user with the target profile and permission set. Navigate the OmniScript or trigger the IP through the full runtime path, including any Experience Cloud or page-level embedding. Verify Navigation Actions execute, permissions are correct, and Named Credentials authenticate successfully.
6. Run UTAM automation if a regression suite exists — If the project maintains UTAM page objects, execute the relevant test suite against the sandbox. Review any failures against the specific page object library for the org's runtime.
7. Document gaps before sign-off — Record any scenarios that could not be covered by in-designer testing (guest-user edge cases, high-concurrency, Named Credential failures) and communicate them to the team before marking the component ready for production.

Review Checklist

Run through these before marking work in this area complete:

• DataRaptor Extract/Transform/Load components validated via Preview with representative test data
• All Integration Procedure steps tested in isolation with vlcStatus = success and no errorMessage
• OmniScript Preview completed; conditional rendering and step navigation confirmed correct
• Component deployed to sandbox and tested as the actual target user profile (not admin)
• Navigation Actions confirmed to execute correctly in deployed runtime
• Named Credentials confirmed active and accessible to the integration user
• UTAM or manual regression test completed if component is part of a regression suite

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Preview mode silently skips Navigation Actions — OmniScript Preview does not execute steps of type Navigation Action (Save, Navigate, Cancel). A script that works perfectly in Preview can fail completely in production if a Navigation Action contains required logic or triggers downstream processes. Always verify Navigation Actions in a deployed runtime.
2. Preview always runs as admin, masking FLS and permission issues — All three in-designer test tools (OmniScript Preview, IP Test Execution, DataRaptor Preview) authenticate as the admin user. Field-Level Security, object permissions, sharing rules, and Experience Cloud guest-user restrictions are invisible in Preview. The most common defect pattern: Preview passes, admin-in-sandbox passes, community guest fails silently with a blank step or missing data.
3. IP Test Execution vlcStatus warning continues execution but drops data — A step that returns vlcStatus: "warning" does not abort the IP — execution continues to the next step. However, the step's output may be partial or empty, silently producing corrupted downstream data. Treat all non-success statuses as failures during testing.
4. UTAM page objects differ between Package Runtime and Standard Runtime — Managed-package (Package Runtime) OmniStudio components render with the vlocity_ins or vlocity_cmt namespace HTML structure; Standard Runtime uses the native structure. Using the wrong UTAM page object library against the wrong runtime produces false test failures. Always confirm the org's runtime before selecting UTAM page objects.

Output Artifacts

Related Skills

• omnistudio-ci-cd-patterns — Use alongside this skill for deploying tested components through DataPack-based pipelines
• omnistudio-datapack-migration — Understand how DataPacks export/import affects component versions before testing