From c912621d1026d1b473af4f9242e8078f2ee303d4 Mon Sep 17 00:00:00 2001
From: Sander <17591696+sand4rt@users.noreply.github.com>
Date: Mon, 3 Jun 2024 18:58:56 +0200
Subject: [PATCH] docs(ct): api reference (#31109)
closes: https://github.com/microsoft/playwright/issues/30581
---
docs/src/test-components-js.md | 303 ++++++++++++++++++++++++++++++++-
1 file changed, 295 insertions(+), 8 deletions(-)
diff --git a/docs/src/test-components-js.md b/docs/src/test-components-js.md
index c618489833..099dc2b362 100644
--- a/docs/src/test-components-js.md
+++ b/docs/src/test-components-js.md
@@ -281,7 +281,179 @@ test('changes the image', async ({ mount }) => {
As a result, for every component you'll have a story file that exports all the stories that are actually tested.
These stories live in the browser and "convert" complex object into the simple objects that can be accessed in the test.
-## Hooks
+## Under the hood
+
+Here is how component testing works:
+
+- Once the tests are executed, Playwright creates a list of components that the tests need.
+- It then compiles a bundle that includes these components and serves it using a local static web server.
+- Upon the `mount` call within the test, Playwright navigates to the facade page `/playwright/index.html` of this bundle and tells it to render the component.
+- Events are marshalled back to the Node.js environment to allow verification.
+
+Playwright is using [Vite](https://vitejs.dev/) to create the components bundle and serve it.
+
+## API reference
+
+### props
+
+Provide props to a component when mounted.
+
+
+
+
+
+```js
+test('props', async ({ mount }) => {
+ const component = await mount();
+});
+```
+
+
+
+
+```js
+test('props', async ({ mount }) => {
+ const component = await mount();
+});
+```
+
+
+
+
+```js
+test('props', async ({ mount }) => {
+ const component = await mount(Component, { props: { msg: 'greetings' } });
+});
+```
+
+
+
+
+```js
+test('props', async ({ mount }) => {
+ const component = await mount(Component, { props: { msg: 'greetings' } });
+});
+```
+
+
+
+
+
+### callbacks / events
+
+Provide callbacks/events to a component when mounted.
+
+
+
+
+
+```js
+test('callback', async ({ mount }) => {
+ const component = await mount( {}} />);
+});
+```
+
+
+
+
+```js
+test('callback', async ({ mount }) => {
+ const component = await mount( {}} />);
+});
+```
+
+
+
+
+```js
+test('event', async ({ mount }) => {
+ const component = await mount(Component, { on: { callback() {} } });
+});
+```
+
+
+
+
+```js
+test('event', async ({ mount }) => {
+ const component = await mount(Component, { on: { callback() {} } });
+});
+```
+
+
+
+
+
+### children / slots
+
+Provide children/slots to a component when mounted.
+
+
+
+
+
+```js
+test('children', async ({ mount }) => {
+ const component = await mount(Child);
+});
+```
+
+
+
+
+```js
+test('children', async ({ mount }) => {
+ const component = await mount(Child);
+});
+```
+
+
+
+
+```js
+test('slot', async ({ mount }) => {
+ const component = await mount(Component, { slots: { default: 'Slot' } });
+});
+```
+
+
+
+
+```js
+test('slot', async ({ mount }) => {
+ const component = await mount(Component, { slots: { default: 'Slot' } });
+});
+```
+
+
+
+
+
+### hooks
You can use `beforeMount` and `afterMount` hooks to configure your app. This lets you setup things like your app router, fake server etc. giving you the flexibility you need. You can also pass custom configuration from the `mount` call from a test, which is accessible from the `hooksConfig` fixture. This includes any config that needs to be run before or after mounting the component. An example of configuring a router is provided below:
@@ -423,16 +595,131 @@ You can use `beforeMount` and `afterMount` hooks to configure your app. This let
-## Under the hood
+### unmount
-Here is how component testing works:
+Unmount the mounted component from the DOM. This is useful for testing the component's behavior upon unmounting. Use cases include testing an "Are you sure you want to leave?" modal or ensuring proper cleanup of event handlers to prevent memory leaks.
-- Once the tests are executed, Playwright creates a list of components that the tests need.
-- It then compiles a bundle that includes these components and serves it using a local static web server.
-- Upon the `mount` call within the test, Playwright navigates to the facade page `/playwright/index.html` of this bundle and tells it to render the component.
-- Events are marshalled back to the Node.js environment to allow verification.
+
-Playwright is using [Vite](https://vitejs.dev/) to create the components bundle and serve it.
+
+
+```js
+test('unmount', async ({ mount }) => {
+ const component = await mount();
+ await component.unmount();
+});
+```
+
+
+
+
+```js
+test('unmount', async ({ mount }) => {
+ const component = await mount();
+ await component.unmount();
+});
+```
+
+
+
+
+```js
+test('unmount', async ({ mount }) => {
+ const component = await mount(Component);
+ await component.unmount();
+});
+```
+
+
+
+
+```js
+test('unmount', async ({ mount }) => {
+ const component = await mount(Component);
+ await component.unmount();
+});
+```
+
+
+
+
+
+### update
+
+Update props, slots/children, and/or events/callbacks of a mounted component. These component inputs can change at any time and are typically provided by the parent component, but sometimes it is necessary to ensure that your components behave appropriately to new inputs.
+
+
+
+
+
+```js
+test('update', async ({ mount }) => {
+ const component = await mount();
+ await component.update(
+ {}}>Child
+ );
+});
+```
+
+
+
+
+```js
+test('update', async ({ mount }) => {
+ const component = await mount();
+ await component.update(
+ {}}>Child
+ );
+});
+```
+
+
+
+
+```js
+test('update', async ({ mount }) => {
+ const component = await mount();
+ await component.update({
+ props: { msg: 'greetings' },
+ on: { callback: () => {} },
+ slots: { default: 'Child' }
+ });
+});
+```
+
+
+
+
+```js
+test('update', async ({ mount }) => {
+ const component = await mount();
+ await component.update({
+ props: { msg: 'greetings' },
+ on: { callback: () => {} },
+ slots: { default: 'Child' }
+ });
+});
+```
+
+
+
+
## Frequently asked questions