Test: Enhance the context with canvas when the test package is used

[kasperpeulen]

What I did

The CSF pull request is here:
ComponentDriven/csf#99

Following up on #28353
Now the context is always the same reference throughout loaders and the play function, we can enhance the context in the @storybook/test package:

storybook/code/lib/test/src/index.ts

Lines 101 to 107 in b9f4f04

	const enhanceContext: LoaderFunction = (context) => {
	if (globalThis.HTMLElement && context.canvasElement instanceof globalThis.HTMLElement) {
	context.canvas = within(context.canvasElement);
	// TODO enable this in a later PR, once we have time to QA this properly
	// context.userEvent = userEvent.setup();
	}
	};

We are adding canvas as just a shortcut for within(canvasElement).

In a later PR we will add userEvent as a shortcut for userEvent.setup() which is a best practice in userEvent, see this issue:
#17988

We use module augmentation to enhance the types when the test package is used:

storybook/code/lib/test/src/index.ts

Lines 20 to 26 in b9f4f04

	declare module '@storybook/csf' {
	interface Canvas extends Queries {}
	interface StoryContext {
	// TODO enable this in a later PR, once we have time to QA this properly
	// userEvent: ReturnType<typeof userEvent.setup>;
	}
	}

I needed unbundle the @storybook/csf package to get module augmentation to work.

We won't document this feature until 9.0, but we will use this feature as part of the mount context property. As await mount() will return context.canvas whenever the test package is used. This return type will contain all the queries of testing library.

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>

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit e9910ce. 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.

[valentinpalkovic]

Do we want to add canvas here as well?

[kasperpeulen]

Canvas is a special type in CSF, that gets augmented here:

storybook/code/lib/test/src/index.ts

Lines 19 to 26 in b9f4f04

	declare module '@storybook/csf' {
	interface Canvas extends Queries {}
	interface StoryContext {
	// TODO enable this in a later PR, once we have time to QA this properly
	// userEvent: ReturnType<typeof userEvent.setup>;
	}
	}

And therefore the StoryContext changes as well:

export interface StoryContext<TRenderer extends Renderer = Renderer, TArgs = Args>
  extends StoryContextForEnhancers<TRenderer, TArgs>,
    Required<StoryContextUpdate<TArgs>> {
  loaded: Record<string, any>;
  abortSignal: AbortSignal;
  canvasElement: TRenderer['canvasElement'];
  hooks: unknown;
  originalStoryFn: StoryFn<TRenderer>;
  viewMode: ViewMode;
  step: StepFunction<TRenderer, TArgs>;
  context: this;
  canvas: Canvas;
}

[ghengeveld]

I don't think canvas should be part of the CSF spec, to be honest. That makes CSF dependent on Testing Library which I don't think is desirable.

[kasperpeulen]

Right, i agree, but it is not coupled, because canvas is empty interface in CSF, that can be implemented by addons such as @storybook/test.

[ghengeveld]

Doesn't it make more sense to set these to null initially? Or perhaps a getter which throws an error when canvas isn't available because @storybook/test isn't installed.

[kasperpeulen]

To make module augmentation work, I needed to implement it as an empty interface in CSF. Therefore according to typescript, it can not be null.

[ghengeveld]

Why not camelCase?

[kasperpeulen]

because iFindCamelCaseHarderToReadForLongerSentences

[ghengeveld]

I suspect this won't be equal, as setup() supposedly creates a new instance of UserEvent.

[kasperpeulen]

Yes, but toEqual doesn't check for reference. Structurally it was equal.