@stencil/playwright 0.0.0-dev

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/LICENSE.md +27 -0
  2. package/README.md +175 -0
  3. package/dist/create-config.d.ts +29 -0
  4. package/dist/index.cjs +7076 -0
  5. package/dist/index.cjs.map +7 -0
  6. package/dist/index.d.ts +7 -0
  7. package/dist/index.js +7055 -0
  8. package/dist/index.js.map +7 -0
  9. package/dist/load-config-meta.d.ts +13 -0
  10. package/dist/matchers/index.d.ts +12 -0
  11. package/dist/matchers/to-have-first-received-event-detail.d.ts +5 -0
  12. package/dist/matchers/to-have-nth-received-event-detail.d.ts +5 -0
  13. package/dist/matchers/to-have-received-event-detail.d.ts +5 -0
  14. package/dist/matchers/to-have-received-event-times.d.ts +5 -0
  15. package/dist/matchers/to-have-received-event.d.ts +5 -0
  16. package/dist/page/event-spy.d.ts +44 -0
  17. package/dist/page/utils/goto.d.ts +12 -0
  18. package/dist/page/utils/index.d.ts +5 -0
  19. package/dist/page/utils/locator.d.ts +21 -0
  20. package/dist/page/utils/set-content.d.ts +14 -0
  21. package/dist/page/utils/spy-on-event.d.ts +3 -0
  22. package/dist/page/utils/wait-for-changes.d.ts +11 -0
  23. package/dist/playwright-declarations.d.ts +105 -0
  24. package/dist/playwright-page.d.ts +8 -0
  25. package/dist/process-constants.d.ts +4 -0
  26. package/dist/test-expect.d.ts +22 -0
  27. package/package.json +76 -0
package/LICENSE.md ADDED
@@ -0,0 +1,27 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2019-present Drifty Co.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
22
+
23
+ -----------------------------------------
24
+ Third-party components, software, and/or libraries (collectively, "components")
25
+ are included under the licenses specified by their authors. For information
26
+ about these third-party licenses, refer to the separate legal notices governing
27
+ such components at NOTICE file at the top level of the package.
package/README.md ADDED
@@ -0,0 +1,175 @@
1
+ # @stencil/playwright
2
+
3
+ Stencil Playwright is a testing adapter package that allows developers to easily use the [Playwright testing framework](https://playwright.dev/docs/intro)
4
+ in their Stencil project.
5
+
6
+ For full documentation, please see the [Playwright testing docs on the official Stencil site](https://stenciljs.com/docs/next/testing/playwright/overview).
7
+
8
+ ## Getting Started
9
+
10
+ 1. Install the necessary packages using your preferred package manager:
11
+
12
+ ```bash
13
+ npm i @stencil/playwright @playwright/test --save-dev
14
+ ```
15
+
16
+ 1. Install Playwright's browser binaries:
17
+
18
+ ```bash
19
+ npx playwright install
20
+ ```
21
+
22
+ 1. Create a `playwright.config.ts` file. The `@stencil/playwright` package offers a utility function to quickly create a default configuration that should
23
+ work for most Stencil projects:
24
+
25
+ ```ts
26
+ // playwright.config.ts
27
+
28
+ import { expect } from '@playwright/test';
29
+ import { matchers, createStencilPlaywrightConfig } from '@stencil/playwright';
30
+
31
+ expect.extend(matchers);
32
+
33
+ export default createStencilPlaywrightConfig();
34
+ ```
35
+
36
+ 1. At this point, any tests can be executed using `npx playwright test` (or by updating the project's test command in the `package.json`). By default, Playwright's test matcher
37
+ is configured to run all tests matching the pattern `*.e2e.ts`. This can be changed by overriding the default matcher using the
38
+ [`createStencilPlaywrightConfig()` function](#createstencilplaywrightconfigoverrides-createstencilplaywrightconfigoptions-promiseplaywrighttestconfig):
39
+
40
+ ```ts
41
+ // playwright.config.ts
42
+
43
+ import { expect } from '@playwright/test';
44
+ import { matchers, createStencilPlaywrightConfig } from '@stencil/playwright';
45
+
46
+ expect.extend(matchers);
47
+
48
+ export default createStencilPlaywrightConfig({
49
+ // Change which test files Playwright will execute
50
+ testMatch: '*.spec.ts',
51
+ // Any other Playwright config option can also be overridden
52
+ });
53
+ ```
54
+
55
+ ## Testing Patterns
56
+
57
+ ### `page.goto()`
58
+
59
+ The `goto()` method allows tests to load a pre-defined HTML template. This pattern is great if a test file has many tests to execute that all use the same HTML code
60
+ or if additional `script` or `style` tags need to be included in the HTML. However, with this pattern, developers are responsible for defining the necessary `script`
61
+ tags pointing to the Stencil entry code (so all web components are correctly loaded and registered).
62
+
63
+ ```html
64
+ <!-- my-component.e2e.html -->
65
+
66
+ <!doctype html>
67
+ <html lang="en">
68
+ <head>
69
+ <meta charset="utf8" />
70
+
71
+ <!-- Replace with the path to your entrypoint -->
72
+ <script src="./build/test-app.esm.js" type="module"></script>
73
+ <script src="./build/test-app.js" nomodule></script>
74
+ </head>
75
+ <body>
76
+ <my-component first="Stencil"></my-component>
77
+ </body>
78
+ </html>
79
+ ```
80
+
81
+ ```ts
82
+ // my-component.e2e.ts
83
+
84
+ import { expect } from '@playwright/test';
85
+ import { test } from '@stencil/playwright';
86
+
87
+ test.describe('my-component', () => {
88
+ test('should render the correct name', async ({ page }) => {
89
+ // The path here is the path to the www output relative to the dev server root directory
90
+ await page.goto('/my-component/my-component.e2e.html');
91
+
92
+ // Rest of test
93
+ });
94
+ });
95
+ ```
96
+
97
+ ### `page.setContent()`
98
+
99
+ The `setContent()` method allows tests to define their own HTML code on a test-by-test basis. This pattern is helpful if the HTML for a test is small, or to
100
+ avoid affecting other tests is using the `page.goto()` pattern and modifying a shared HTML template file. With this pattern, the `script` tags pointing to Stencil
101
+ entry code will be automatically injected into the generated HTML.
102
+
103
+ ```ts
104
+ // my-component.e2e.ts
105
+
106
+ import { expect } from '@playwright/test';
107
+ import { test } from '@stencil/playwright';
108
+
109
+ test.describe('my-component', () => {
110
+ test('should render the correct name', async ({ page }) => {
111
+ await page.setContent('<my-component first="Stencil"></my-component>');
112
+
113
+ // Rest of test
114
+ });
115
+ });
116
+ ```
117
+
118
+ ## API
119
+
120
+ ### `createStencilPlaywrightConfig(overrides?: CreateStencilPlaywrightConfigOptions): Promise<PlaywrightTestConfig>`
121
+
122
+ Returns a [Playwright test configuration](https://playwright.dev/docs/test-configuration#introduction).
123
+
124
+ `overrides`, as the name implies, will overwrite the default configuration value(s) if supplied. These values can include any valid Playwright config option as well
125
+ as some options to override specific values in the config options related to the Stencil integration:
126
+
127
+ - `webServerCommand`: This can be specified to change the command that will run to start the Stencil dev server. Defaults to `npm start -- --no-open`.
128
+ - `webServerTimeout`: This can be specified to change the amount of time Playwright will wait for the dev server to start. Defaults to 60 seconds.
129
+
130
+ ```ts
131
+ // playwright.config.ts
132
+
133
+ import { expect } from '@playwright/test';
134
+ import { matchers, createStencilPlaywrightConfig } from '@stencil/playwright';
135
+
136
+ expect.extend(matchers);
137
+
138
+ export default createStencilPlaywrightConfig({
139
+ // Change which test files Playwright will execute
140
+ testMatch: '*.spec.ts',
141
+
142
+ // Only wait max 30 seconds for server to start
143
+ webServerTimeout: 30000,
144
+ });
145
+ ```
146
+
147
+ ### `test`
148
+
149
+ `test` designates which tests will be executed by Playwright. See the [Playwright API documentation](https://playwright.dev/docs/api/class-test#test-call) regarding usage.
150
+
151
+ This package modifies the [`page` fixture](#page) and offers a [`skip` utility](#skip) as discussed below.
152
+
153
+ #### `page`
154
+
155
+ The page fixture is a class that allows interacting with the current test's browser tab. In addition to the [default Playwright Page API](https://playwright.dev/docs/api/class-page),
156
+ Stencil extends the class with a few additional methods:
157
+
158
+ - `waitForChanges()`: Waits for Stencil components to re-hydrate before continuing.
159
+ - `spyOnEvent()`: Creates a new EventSpy and listens on the window for an event to emit.
160
+
161
+ #### `skip`
162
+
163
+ The `skip` utility allows developers to skip tests for certain browsers or [component modes](https://stenciljs.com/docs/styling#style-modes):
164
+
165
+ ```ts
166
+ test('my-test', ({ page, skip }) => {
167
+ // Skip tests for certain browsers
168
+ skip.browser('firefox', 'This behavior is not available on Firefox');
169
+
170
+ // Skip tests for certain modes
171
+ skip.mode('md', 'This behavior is not available in Material Design');
172
+
173
+ ...
174
+ })
175
+ ```
package/dist/create-config.d.ts ADDED
@@ -0,0 +1,29 @@
1
+ import { PlaywrightTestConfig } from '@playwright/test';
2
+ /**
3
+ * Options for creating a Playwright config for Stencil projects. This extends the default Playwright config
4
+ * with some additional options specific to overriding options for the Playwright dev server.
5
+ */
6
+ export type CreateStencilPlaywrightConfigOptions = Partial<PlaywrightTestConfig> & {
7
+ /**
8
+ * The command to execute to start the dev server. This can be a bash command or a local npm script.
9
+ *
10
+ * Defaults to `npm start -- --no-open`.
11
+ */
12
+ webServerCommand?: string;
13
+ /**
14
+ * The maximum time to wait for the dev server to start before aborting.
15
+ *
16
+ * Defaults to `60000` (60 seconds).
17
+ */
18
+ webServerTimeout?: number;
19
+ };
20
+ /**
21
+ * Helper function to easily create a Playwright config for Stencil projects. This function will
22
+ * automatically load the Stencil config meta to set default values for the Playwright config respecting the
23
+ * Stencil dev server configuration, and set the Stencil namespace and entry path as environment variables for use
24
+ * in the Playwright tests.
25
+ *
26
+ * @param overrides Values to override in the default config. Any Playwright config option can be overridden.
27
+ * @returns A {@link PlaywrightTestConfig} object
28
+ */
29
+ export declare const createStencilPlaywrightConfig: (overrides?: CreateStencilPlaywrightConfigOptions) => Promise<PlaywrightTestConfig>;