Shadow DOM Interaction Script Generation Prompt

This prompt is built for automation engineers and SDETs who are blocked by Web Component encapsulation. Standard locators like CSS selectors and XPath fail when an application under test uses Lit, Stencil, or native custom elements with open or closed Shadow DOM. The core job-to-be-done is piercing shadow roots, verifying content rendered into <slot> elements, and asserting events that must cross shadow boundaries. Use this prompt when you can provide the component's approximate HTML structure, the target framework, and the sequence of user interactions you need to automate. It is not a general-purpose test generator; it is a surgical tool for the high-friction problem of Shadow DOM traversal.

The prompt requires specific context to produce a reliable script. You must supply the component's outer HTML or a structural description, the framework in use (Lit, Stencil, Angular with ViewEncapsulation.ShadowDom, or native custom elements), the target browser engine, and the interaction steps with expected outcomes. The prompt assumes you are working in Playwright, Puppeteer, or a similar browser automation tool that exposes shadowRoot accessors and >> or >>> piercing combinators. It will not generate correct scripts for tools that lack native Shadow DOM support or for environments where polyfills alter the standard encapsulation behavior. If your component uses closed Shadow DOM (mode: 'closed'), the prompt will explicitly flag the limitation and suggest alternative strategies, such as injecting test hooks or using framework-specific devtools APIs.

Do not use this prompt for standard DOM testing, iframe isolation, or basic visibility assertions. It is overkill for applications built entirely with light DOM frameworks like React or Vue without Shadow DOM. The prompt also does not replace a full test suite architect; it generates a single interaction script scaffold. You are responsible for integrating the output into your page object models, adding retry logic, and validating the script against your application's actual rendering behavior. Before running the generated script in CI, review the selector chain for brittleness, confirm that slot assignments match your component's runtime behavior, and add explicit assertions for any cross-boundary events your test must verify.

This prompt template is designed to produce a test automation script that can reliably pierce a Web Component's Shadow DOM, interact with encapsulated elements, and verify slot content. It is framework-agnostic in its instruction but expects you to specify your target automation library (Playwright, Selenium, Cypress) and the component's technical details. The output should be a script that handles both open and closed shadow roots where possible, includes explicit wait strategies for shadow DOM readiness, and provides fallback selectors.

markdownCopy
Generate a test automation script using [TEST_FRAMEWORK] that interacts with the Web Component defined below. The script must pierce the component's Shadow DOM to perform actions and assertions on encapsulated elements.

## Component Context
- **Component Tag:** [COMPONENT_TAG_NAME]
- **Shadow DOM Mode:** [OPEN_MODE_OR_CLOSED_MODE]
- **Slot Content to Verify:** [DESCRIBE_SLOTTED_CONTENT]
- **Internal Elements to Interact With:** [DESCRIBE_INTERNAL_ELEMENTS_AND_ACTIONS]
- **Expected Behavior:** [DESCRIBE_EXPECTED_OUTCOMES_AND_EVENTS]

## Script Requirements
1.  **Shadow Root Access:** Use the framework's native method for piercing shadow roots (e.g., `shadowRoot` property, `pierce/` selectors, or JavaScript execution). If the mode is 'closed', provide a JavaScript workaround or clearly state the limitation.
2.  **Wait Strategy:** Replace all static sleeps with explicit waits that confirm the shadow root and its target elements are attached and visible.
3.  **Selector Strategy:** Use a prioritized chain of selectors: `data-testid` attributes first, then `aria` labels, then `id`, and finally CSS selectors. Provide a comment explaining the fallback logic.
4.  **Assertions:** Include precise assertions for:
    - The presence and content of slotted elements.
    - The state of internal elements after interaction (e.g., button disabled, text updated).
    - Any custom events fired across the shadow boundary.
5.  **Error Handling:** Wrap interactions in try-catch blocks and log descriptive errors if the shadow root or target element is not found.

## Output Format
Provide only the script code in a single fenced code block. Include brief comments for complex logic.

To adapt this template, replace each [PLACEHOLDER] with your specific test scenario details. For [TEST_FRAMEWORK], specify the exact library and language (e.g., Playwright in TypeScript). The [OPEN_MODE_OR_CLOSED_MODE] field is critical; if the mode is 'closed', the generated script must acknowledge that standard shadow root piercing will fail and should attempt to override Element.prototype.attachShadow as a workaround or log a clear limitation. After generating the script, you must validate that the wait strategy does not rely on arbitrary timeouts and that the selectors are not brittle, single-attribute CSS paths.

This prompt is designed to be called programmatically from a test generation service or CLI tool, not used as a one-off chat. The harness should receive a test case description, target component metadata, and the target framework (Playwright, Cypress, or Selenium) as structured inputs. Before calling the LLM, validate that the component name and shadow host selector are present—missing selectors are the most common cause of unusable output. The prompt expects a [FRAMEWORK] parameter; map this from your test configuration and reject unsupported values before the API call to avoid wasting tokens on a framework the model will hallucinate support for.

After receiving the generated script, run a multi-stage validation pipeline. First, perform static checks: confirm the output contains at least one shadow root piercing call (shadowRoot, shadow(), or framework equivalent), verify that slot content assertions use assignedNodes() or assignedElements() rather than naive child traversal, and check that closed-mode shadow DOM is explicitly flagged as inaccessible with a fallback comment. Second, execute the script in a sandboxed browser environment against a known test fixture that includes both open and closed shadow trees. A script that passes static checks but fails at runtime due to a stale element reference or incorrect shadow boundary traversal should trigger a retry with the error message appended to the [CONTEXT] field. Limit retries to two attempts; after that, flag the output for human review and log the failure mode for selector strategy refinement.

For production use, store the generated script alongside metadata: the model version, prompt version, framework, and whether the script passed sandbox execution. This traceability is critical because shadow DOM APIs evolve (e.g., Playwright's locator() piercing behavior changed across versions). When your framework or component library upgrades, re-run the sandbox validation suite against all stored scripts and flag any that now fail. Do not auto-regenerate without human approval—shadow DOM selectors often encode domain knowledge about the component's internal structure that a model cannot reliably infer from a test case description alone. The harness should treat this prompt as an accelerator for SDETs, not a replacement for their judgment about selector resilience and cross-component coupling.