Docs: Add docs for mounting inside the play function #28444

kasperpeulen · 2024-07-03T21:46:18Z

Closes #

What I did

Add docs for mounting inside the play function

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/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 canary-release-pr.yml --field pr=<PR_NUMBER>

greptile-apps

PR Summary

Added docs/_snippets/before-each-in-preview.md for beforeEach function usage in preview files.
Added docs/_snippets/mount-advanced.md with advanced mounting examples for React, Svelte, and Vue3.
Added docs/_snippets/mount-basic.md with basic mounting examples using MockDate.
Updated docs/api/doc-blocks/doc-block-story.mdx to include a Callout about autoplay requirement for mount.
Enhanced docs/writing-tests/interaction-testing.mdx with detailed guidance on mounting inside the play function.

_{5 file(s) reviewed, no comment(s)}
_{Edit PR Review Bot Settings}

nx-cloud · 2024-07-03T21:52:19Z

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 3e0adbd. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

✅ Successfully ran 1 target

nx run-many -t build --parallel=3

Sent with 💌 from NxCloud.

yannbf

Looks good! I added a few comments, please check them out.
Would be nice to have @kylegach take a look at this after he is back!

docs/_snippets/mount-basic.md

docs/_snippets/mount-advanced.md

docs/writing-tests/interaction-testing.mdx

Co-authored-by: Yann Braga <[email protected]>

…ount-docs

code/core/src/preview-errors.ts

docs/api/doc-blocks/doc-block-story.mdx

docs/writing-tests/interaction-testing.mdx

yannbf

Changes look good but I'd love for @kylegach to take a pass at them

Co-authored-by: Yann Braga <[email protected]>

docs/api/doc-blocks/doc-block-story.mdx

docs/writing-tests/interaction-testing.mdx

valentinpalkovic · 2024-07-08T14:00:13Z

I think we should call out that when the mount function is used to actually pass in a new JSXElement with modified arguments, these are NOT synced to the controls panel. Is this a limitation we want to document or actually a bug?

kasperpeulen · 2024-07-08T14:55:24Z

@valentinpalkovic A custom render function has the exact same limitation right?

The mount args are really implemented as lazy render function, so every limitation with the render function will also apply to the mount args.

valentinpalkovic · 2024-07-08T14:56:20Z

That's correct. Still, this limitation should be highlighted and mentioned.

kasperpeulen · 2024-07-08T15:00:40Z

@valentinpalkovic But do you mean in both the render and mount docs then?

valentinpalkovic · 2024-07-08T15:04:36Z

Yes, if it isn't part of the render docs, then for sure!

- Prose tweaks, adding links for context - Use `If` blocks for conditional content - Restructure content to be story, component, project-ordered - Update headings to be problem-oriented

kylegach · 2024-07-08T21:02:12Z

docs/writing-tests/interaction-testing.mdx

@@ -56,24 +56,71 @@ Once the story loads in the UI, it simulates the user's behavior and verifies th

 <Video src="../_assets/writing-tests/addon-interaction-example-optimized.mp4" />

-### Run code before each test
+<If notRenderer="angular">


I opted to conditionally render this content so that Angular viewers don't even see this feature they cannot use.

But should we render fallback content showing them how to use story-level beforeEach? @kasperpeulen

I like this! My feeling is that displaying the current 'beforeEach' docs for Angular is sufficient. I'm collaborating with the vitest team to enhance the regex for Angular compatibility.

kylegach · 2024-07-08T21:03:08Z

docs/writing-tests/interaction-testing.mdx

+  2. Your Storybook framework or builder must be configured to transpile to ES2017 or newer. This is because destructuring statements and async/await usages are otherwise transpiled away, which prevents Storybook from recognizing your usage of `mount`.
+</Callout>
+
+<If renderer={['react', 'vue', 'svelte']}>


Given that the snippets are only available for these renderers, it seemed like the feature itself only worked for these, so I conditionally rendered this section.

Is there appropriate fallback content for the others? @kasperpeulen

The fallback is kind of the basic-mount example, which will be displayed above this, so I think this is fine!

kylegach · 2024-07-08T21:03:41Z

docs/writing-tests/interaction-testing.mdx

+<Callout variant="warning">
+  There are two requirements to use the `mount` function:
+
+  1. You *must* destructure the mount property from the `context` (the argument passed to your play function). This makes sure that Storybook does not start rendering the story before the play function begins.
+  2. Your Storybook framework or builder must be configured to transpile to ES2017 or newer. This is because destructuring statements and async/await usages are otherwise transpiled away, which prevents Storybook from recognizing your usage of `mount`.
+</Callout>


If you like the way I reworded this, I suggest updating the error message changed in the PR to match.

I like this, but I feel that the error message in Storybook should still explicitly point out Angular.

…ssage

Docs: Add docs for mounting inside the play function

Add docs for mounting inside the play function

25a0266

kasperpeulen added documentation ci:docs Run the CI jobs for documentation checks only. labels Jul 3, 2024

kasperpeulen requested review from kylegach and cdedreuille July 3, 2024 21:46

greptile-apps bot reviewed Jul 3, 2024

View reviewed changes

kasperpeulen requested a review from yannbf July 3, 2024 22:23

yannbf approved these changes Jul 4, 2024

View reviewed changes

yannbf mentioned this pull request Jul 4, 2024

Docs: Document portable stories usage #28452

Merged

8 tasks

kasperpeulen and others added 13 commits July 8, 2024 11:31

Update docs/_snippets/mount-basic.md

530b337

Co-authored-by: Yann Braga <[email protected]>

Update docs/_snippets/mount-basic.md

8fb62c4

Co-authored-by: Yann Braga <[email protected]>

Update docs/_snippets/mount-basic.md

a84504f

Co-authored-by: Yann Braga <[email protected]>

Update docs/writing-tests/interaction-testing.mdx

ed48d74

Co-authored-by: Yann Braga <[email protected]>

Update docs/writing-tests/interaction-testing.mdx

45a83bd

Co-authored-by: Yann Braga <[email protected]>

Update docs/writing-tests/interaction-testing.mdx

58ea726

Co-authored-by: Yann Braga <[email protected]>

Get the canvas from the mount return

ffa7c65

Merge remote-tracking branch 'origin/kasper/mount-docs' into kasper/m…

0f13b9e

…ount-docs

Address feedback

92efbe4

Merge remote-tracking branch 'refs/remotes/origin/next' into kasper/m…

64a6cc2

…ount-docs

Improve message

c471d07

Merge remote-tracking branch 'refs/remotes/origin/next' into kasper/m…

851c37c

…ount-docs

Align error message with docs

efe1a6f

yannbf reviewed Jul 8, 2024

View reviewed changes

code/core/src/preview-errors.ts Outdated Show resolved Hide resolved

yannbf reviewed Jul 8, 2024

View reviewed changes

code/core/src/preview-errors.ts Outdated Show resolved Hide resolved

yannbf reviewed Jul 8, 2024

View reviewed changes

docs/api/doc-blocks/doc-block-story.mdx Outdated Show resolved Hide resolved

yannbf reviewed Jul 8, 2024

View reviewed changes

docs/writing-tests/interaction-testing.mdx Outdated Show resolved Hide resolved

yannbf reviewed Jul 8, 2024

View reviewed changes

docs/writing-tests/interaction-testing.mdx Outdated Show resolved Hide resolved

yannbf approved these changes Jul 8, 2024

View reviewed changes

Update docs/writing-tests/interaction-testing.mdx

87bea60

Co-authored-by: Yann Braga <[email protected]>

kasperpeulen and others added 3 commits July 8, 2024 14:14

Update docs/writing-tests/interaction-testing.mdx

e683be2

Co-authored-by: Yann Braga <[email protected]>

Update code/core/src/preview-errors.ts

0514a5c

Co-authored-by: Yann Braga <[email protected]>

Update code/core/src/preview-errors.ts

f8def35

Co-authored-by: Yann Braga <[email protected]>

shilman approved these changes Jul 8, 2024

View reviewed changes

docs/api/doc-blocks/doc-block-story.mdx Outdated Show resolved Hide resolved

docs/writing-tests/interaction-testing.mdx Outdated Show resolved Hide resolved

Updates

f1b57d0

- Prose tweaks, adding links for context - Use `If` blocks for conditional content - Restructure content to be story, component, project-ordered - Update headings to be problem-oriented

kylegach reviewed Jul 8, 2024

View reviewed changes

kasperpeulen and others added 5 commits July 9, 2024 11:44

Add note about disabling controls for async args and improve error me…

3a8538c

…ssage

Add Angular fallback guidance

a31b882

Merge branch 'next' into kasper/mount-docs

d192df3

Add beforeAll section

f73dc21

Merge branch 'next' into kasper/mount-docs

3e0adbd

kylegach merged commit c226334 into next Jul 10, 2024
11 checks passed

kylegach deleted the kasper/mount-docs branch July 10, 2024 19:00

github-actions bot mentioned this pull request Jul 10, 2024

Release: Prerelease 8.3.0-alpha.1 #28509

Merged

33 tasks

kylegach added a commit that referenced this pull request Jul 10, 2024

Merge pull request #28444 from storybookjs/kasper/mount-docs

858f1b6

Docs: Add docs for mounting inside the play function

kylegach mentioned this pull request Jul 10, 2024

Docs: Updates for 8.2 features #28534

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Add docs for mounting inside the play function #28444

Docs: Add docs for mounting inside the play function #28444

kasperpeulen commented Jul 3, 2024

greptile-apps bot left a comment

nx-cloud bot commented Jul 3, 2024 •

edited

Loading

yannbf left a comment

yannbf left a comment

valentinpalkovic commented Jul 8, 2024

kasperpeulen commented Jul 8, 2024

valentinpalkovic commented Jul 8, 2024

kasperpeulen commented Jul 8, 2024

valentinpalkovic commented Jul 8, 2024

kylegach Jul 8, 2024

kasperpeulen Jul 9, 2024 •

edited

Loading

kylegach Jul 8, 2024

kasperpeulen Jul 9, 2024

kylegach Jul 8, 2024

kasperpeulen Jul 9, 2024

Docs: Add docs for mounting inside the play function #28444

Docs: Add docs for mounting inside the play function #28444

Conversation

kasperpeulen commented Jul 3, 2024

What I did

Checklist for Contributors

Testing

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

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

greptile-apps bot left a comment

Choose a reason for hiding this comment

PR Summary

nx-cloud bot commented Jul 3, 2024 • edited Loading

☁️ Nx Cloud Report

yannbf left a comment

Choose a reason for hiding this comment

yannbf left a comment

Choose a reason for hiding this comment

valentinpalkovic commented Jul 8, 2024

kasperpeulen commented Jul 8, 2024

valentinpalkovic commented Jul 8, 2024

kasperpeulen commented Jul 8, 2024

valentinpalkovic commented Jul 8, 2024

kylegach Jul 8, 2024

Choose a reason for hiding this comment

kasperpeulen Jul 9, 2024 • edited Loading

Choose a reason for hiding this comment

kylegach Jul 8, 2024

Choose a reason for hiding this comment

kasperpeulen Jul 9, 2024

Choose a reason for hiding this comment

kylegach Jul 8, 2024

Choose a reason for hiding this comment

kasperpeulen Jul 9, 2024

Choose a reason for hiding this comment

nx-cloud bot commented Jul 3, 2024 •

edited

Loading

kasperpeulen Jul 9, 2024 •

edited

Loading