Core: Enhance warning for Testing Library's screen usage in docs mode

[yannbf]

Closes #31598

What I did

This PR scopes the TL screen warning so it only really warns when a story which uses the screen utility is rendered in docs mode

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

• Bug Fixes
  • Refined Testing Library warning behavior so alerts only appear in Storybook docs view, providing contextual guidance there and remaining silent during normal development. The change also improves robustness against cross-origin environments to avoid spurious warnings.

[coderabbitai]

📝 Walkthrough

Walkthrough

A runtime guard was added to the Testing Library screen proxy: the proxy no longer emits an unconditional warning on access. The warning now only runs when the environment appears to be Storybook docs view (detected via location.viewMode or /docs/ in parent/global location), and access still returns Reflect.get(...).

Changes

Cohort / File(s)	Change Summary
Testing Library proxy warning logic code/core/src/test/testing-library.ts	Replaced unconditional warning on Testing Library screen proxy access with a conditional check that detects Storybook docs mode (checks location.viewMode === 'docs' and .../docs/ in parent/global location). Warning emission is guarded by try/catch to avoid cross-origin errors; proxy still returns Reflect.get(target, prop, receiver) in all cases.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Caller as Test Code
    participant Proxy as TestingLibrary.screen Proxy
    participant Env as Global Window / Parent

    Caller->>Proxy: access property (e.g., screen.foo)
    Proxy->>Env: try read location / parent.location
    alt Env indicates docs view (viewMode=docs or /docs/ in path)
        Proxy-->>Caller: log docs-mode guidance warning
    else Not docs view or cross-origin error
        Proxy-->>Caller: (no warning)
    end
    Proxy-->>Caller: return Reflect.get(target, prop, receiver)
    note right of Proxy #ddeeff: try/catch used to avoid\ncross-origin errors when reading locations

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Single-file change with localized conditional logic.
• Pay attention to the environment-detection logic and try/catch around cross-origin access.
• Verify warning message wording and that return value remains Reflect.get(...).

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch yann/scope-tl-screen-warning

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b1be709 and a66d817.

📒 Files selected for processing (1)

• code/core/src/test/testing-library.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• code/core/src/test/testing-library.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: normal
• GitHub Check: Core Unit Tests, windows-latest

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between aba3791 and b1be709.

📒 Files selected for processing (1)

• code/core/src/test/testing-library.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (4)

**/*.{js,jsx,json,html,ts,tsx,mjs}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.{js,jsx,json,html,ts,tsx,mjs}: Run Prettier formatting on changed files before committing
Run ESLint on changed files and fix all errors/warnings before committing (use yarn lint:js:cmd <file>)

Files:

• code/core/src/test/testing-library.ts

**/*.{ts,tsx,js,jsx,mjs}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Export functions from modules when they need to be unit-tested

Files:

• code/core/src/test/testing-library.ts

code/**/*.{ts,tsx,js,jsx,mjs}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

In application code, use Storybook loggers instead of console.* (client code: storybook/internal/client-logger; server code: storybook/internal/node-logger)

Files:

• code/core/src/test/testing-library.ts

{code/**,scripts/**}/**/*.{ts,tsx,js,jsx,mjs}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Do not use console.log, console.warn, or console.error directly unless in isolated files where importing loggers would significantly increase bundle size

Files:

• code/core/src/test/testing-library.ts

🧬 Code graph analysis (1)

code/core/src/test/testing-library.ts (2)

code/renderers/web-components/template/components/Html.js (1)

• globalThis (5-5)

scripts/utils/tools.ts (1)

• dedent (118-118)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: normal
• GitHub Check: Core Unit Tests, windows-latest

[nx-cloud]

View your CI Pipeline Execution ↗ for commit f40907a

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	45s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-10-27 14:20:24 UTC