@jscutlery/playwright-ct-angular 0.3.0 → 0.5.0

package/README.md

@@ -1,32 +1,64 @@
 # Playwright Component Testing for Angular _(experimental)_
 
-This library brings **Angular support** to [Playwright's **experimental** Component Testing](https://playwright.dev/docs/test-components).
+This library brings **Angular support** to [Playwright's **experimental
+** Component Testing](https://playwright.dev/docs/test-components).
 
-This will allow us to test our Angular components with Playwright without building the whole app and with more control.
+This will allow you to test your Angular components with Playwright without building the whole app and with more
+control.
 
 `@jscutlery/playwright-ct-angular` currently supports:
 
-- ✅ **Testing [Versatile Angular Components](https://marmicode.io/blog/versatile-angular)**
-- 🎛 **Passing type-safe inputs to the tested components** 
-- 🎭 **Spying on component outputs in a type-safe fashion**
+- ✅ **Testing Angular components/directives/pipes**
+- 🎛 **Controlling inputs/outputs in a type-safe fashion**
+- 🥸 **Overriding providers**
+- 🍳 **Testing with templates**
 
 https://user-images.githubusercontent.com/2674658/206226065-ba856329-dda7-43b1-9c28-4416b190f4d4.mp4
 
-# 🚀 Writing our first
-
-First, we will have to set up Playwright Component Testing as [mentioned below](#setup).
+# Table of Contents
+
+<!-- TOC -->
+
+* [Playwright Component Testing for Angular _(experimental)_](#playwright-component-testing-for-angular-_experimental_)
+* [Table of Contents](#table-of-contents)
+* [🚀 Writing your first test](#-writing-your-first-test)
+    * [✅ Basic Test](#-basic-test)
+    * [🎛 Testing Inputs](#-testing-inputs)
+        * [Passing output callbacks](#passing-output-callbacks)
+    * [🥸 Providing Test Doubles & Importing Additional Modules](#-providing-test-doubles--importing-additional-modules)
+    * [🎨 Using Styles](#-using-styles)
+        * [Shared Styles](#shared-styles)
+        * [Specific Styles](#specific-styles)
+        * [Angular Material & Angular Libraries with styles](#angular-material--angular-libraries-with-styles)
+    * [More examples](#more-examples)
+* [⚠️ Known Limitations](#-known-limitations)
+    * [🪄 The Magic Behind the Scenes](#-the-magic-behind-the-scenes)
+    * [It is currently impossible to...](#it-is-currently-impossible-to)
+        * [...hold the component type in a variable](#hold-the-component-type-in-a-variable)
+        * [...use the component type elsewhere in the file.](#use-the-component-type-elsewhere-in-the-file)
+        * [...declare components in the same file.](#declare-components-in-the-same-file)
+* [📦 Setup](#-setup)
+    * [1. Install](#1-install)
+    * [2. Configure](#2-configure)
+    * [3. Change tests extension](#3-change-tests-extension)
+
+<!-- TOC -->
+
+# 🚀 Writing your first test
+
+First, you will have to set up Playwright Component Testing as [mentioned below](#setup).
 
 ⚠️ Make sure to check the [known limitations](#-known-limitations) before writing more tests.
 
 ## ✅ Basic Test
 
-Then, we can write our first test in `.../src/greetings.component.pw.ts`:
+Then, you can write your first test in `.../src/greetings.component.pw.ts`:
 
 ```ts
 import { expect, test } from '@jscutlery/playwright-ct-angular';
 import { GreetingsComponent } from './greetings.component';
 
-test('<jc-greetings> should be polite', async ({ mount }) => {
+test(`GreetingsComponent should be polite`, async ({ mount }) => {
   const locator = await mount(GreetingsComponent);
   expect(locator).toHaveText('👋 Hello!');
 });
@@ -38,38 +70,20 @@ test('<jc-greetings> should be polite', async ({ mount }) => {
 import { expect, test } from '@jscutlery/playwright-ct-angular';
 import { GreetingsComponent } from './greetings.component';
 
-test('<jc-greetings> should be polite', async ({ mount }) => {
-  const locator = await mount(GreetingsComponent, {inputs: {name: 'Edouard'}});
+test(`GreetingsComponent should be polite`, async ({ mount }) => {
+  const locator = await mount(GreetingsComponent, { props: { name: 'Edouard' } });
   expect(locator).toHaveText('👋 Hello Edouard!');
 });
 ```
 
-## 🎭 Spying on outputs
-
-`mount()` will automatically create a `jest-mock`'s spy, subscribe to the outputs given through the `spyOutputs`
-option and return them in the `spies` property, in a type-safe way showing only the outputs that are spied on.
-
-Note that the `spyOutputs` is type-safe and will only allow properties that exist on the component.
-
-```ts
-import { expect, test } from '@jscutlery/playwright-ct-angular';
-import { NameEditorComponent } from './name-editor.component';
-
-test('<jc-name-editor> should be polite', async ({ mount }) => {
-  const locator = await mount(NameEditorComponent, {spyOutputs: ['nameChange']});
-
-  await locator.getByLabel('Name').type('Edouard');
-
-  expect(locator.spies.nameChange).lastCalledWith('Edouard');
-});
-```
-
 ### Passing output callbacks
 
-We can also pass custom output callback functions for some extreme cases or if we want to use a custom spy implementation for example or just debug.
+You can also pass custom output callback functions for some extreme cases or if you want to use a custom spy
+implementation for example or just debug.
+
 ```ts
 await mount(NameEditorComponent, {
-  outputs: {
+  on: {
     nameChange(name) {
       console.log(name);
     }
@@ -89,7 +103,7 @@ import { RecipeSearchTestContainer } from './recipe-search.test-container';
 
 test('...', async ({ mount }) => {
   await mount(RecipeSearchTestContainer, {
-    inputs: {
+    props: {
       recipes: [
         beer,
         burger
@@ -112,20 +126,24 @@ test('...', async ({ mount }) => {
   ],
 })
 export class RecipeSearchTestContainer {
-  private _repo = inject(RecipeRepositoryFake);
-
-  @Input() set recipes(recipes: Recipe[]) {
-    this._repo.recipes = recipes;
-  }
+  recipes = input<Recipe[]>([]);
+  #repo = inject(RecipeRepositoryFake);
+  #syncRecipesWithRepo = effect(() => {
+    this.#repo.setRecipes(this.recipes());
+  });
 }
 
 /* Cf. https://github.com/jscutlery/devkit/tree/main/tests/playwright-ct-angular-wide/src/testing/recipe-repository.fake.ts
  * for a better example. */
 class RecipeRepositoryFake implements RecipeRepositoryDef {
-  recipes: Recipe[] = [];
+  #recipes: Recipe[] = [];
 
   searchRecipes() {
-    return defer(() => of(this.recipes));
+    return defer(() => of(this.#recipes));
+  }
+
+  setRecipes(recipes: Recipe[]) {
+    this.#recipes = recipes;
   }
 }
 ```
@@ -134,30 +152,36 @@ class RecipeRepositoryFake implements RecipeRepositoryDef {
 
 ### Shared Styles
 
-In order to import styles that are shared between our tests, we can do so by importing them in `playwright/index.ts`.
-We can also customize the shared `playwright/index.html` nearby.
+In order to import styles that are shared between your tests, you can do so by importing them in `playwright/index.ts`.
+You can also customize the shared `playwright/index.html` nearby.
 
 ### Specific Styles
 
-If we want to load some specific styles for a single test, we might prefer using a test container component:
+If you want to load some specific styles for a single test, you might prefer using a test container component:
+
 ```ts
 import styles from './some-styles.css';
+
 @Component({
   template: '<jc-greetings></jc-greetings>',
   encapsulation: ViewEncapsulation.None,
   styles: [styles]
 })
-class GreetingsTestContainer {}
+class GreetingsTestContainer {
+}
 ```
 
 ### Angular Material & Angular Libraries with styles
 
 As mentioned in [Versatile Angular Style Blog Post](https://marmicode.io/blog/versatile-angular),
-Angular Material and other Angular libraries might use a [Conditional "style" Export](https://nodejs.org/api/packages.html#conditional-exports)
+Angular Material and other Angular libraries might use
+a [Conditional "style" Export](https://nodejs.org/api/packages.html#conditional-exports)
 that allows us to import prebuilt styles
-_(Cf. [Angular Package Format](https://angular.io/guide/angular-package-format) [managing assets in a library](https://angular.io/guide/creating-libraries#managing-assets-in-a-library))_.
+_(
+Cf. [Angular Package Format](https://angular.io/guide/angular-package-format) [managing assets in a library](https://angular.io/guide/creating-libraries#managing-assets-in-a-library))_.
 
 In that case, we can add the following configuration to our `playwright-ct.config.ts`:
+
 ```ts
 const config: PlaywrightTestConfig = {
   // ...
@@ -174,28 +198,34 @@ const config: PlaywrightTestConfig = {
 ```
 
 ## More examples
-Cf. [/tests/playwright-ct-angular-wide/src](https://github.com/jscutlery/devkit/tree/main/tests/playwright-ct-angular-wide/src)
+
+Cf. [/tests/playwright-ct-angular-demo/src](https://github.com/jscutlery/devkit/tree/main/tests/playwright-ct-angular-demo/src)
 
 # ⚠️ Known Limitations
 
-The way Playwright Component Testing works is different from the way things work with Karma, Jest, Vitest, Cypress etc...
-Playwright Component Testing tests run in a Node.js environment while the component is rendered in a browser.
+The way Playwright Component Testing works is different from the way things work with Karma, Jest, Vitest, Cypress
+etc...
+Playwright Component Testing tests run in a Node.js environment and control the browser through Chrome DevTools
+Protocol, while the component is rendered in a browser.
 
-This causes a couple of limitations as we can't directly access the `TestBed's` or the component's internals,
-and we can only exchange serializable data with the component.
+This causes a couple of limitations as we can't directly access the `TestBed`'s or the component's internals,
+and **we can only exchange serializable data with the component**.
 
 ## 🪄 The Magic Behind the Scenes
 
 The magical workaround behind the scenes is that at build time:
+
 1. Playwright analyses all the calls to `mount()`,
-2. it grabs the first parameter (the component class),
+2. it grabs the arguments (e.g. the component class),
 3. replaces the component class with a unique string (constructed from the component class name and es-module),
-4. adds the component's es-module to Vite entrypoints,
-5. and finally creates a map matching each unique string to the right es-module.
+4. adds the component's ES module to Vite entrypoints,
+5. and finally creates a map matching each unique string to the right ES module.
 
-This way, when calling `mount()`, Playwright with communicate the unique string to the browser who will know which es-module to load.
+This way, when calling `mount()`, Playwright will communicate the unique string to the browser who will know which
+ES module to load.
 
 Cf. https://youtu.be/y3YxX4sFJbM
+
 Cf. https://github.com/microsoft/playwright/blob/cac67fb94f2c8a0ee82878054c39790e660f17ca/packages/playwright-test/src/tsxTransform.ts#L153
 
 ## It is currently impossible to...
@@ -212,44 +242,30 @@ await mount(cmp);
 
 ```ts
 // 🛑 this won't work
-test(MyComponent.name, async ({ mount }) => {});
+test(MyComponent.name, async ({ mount }) => {
+});
 ```
 
 ### ...declare components in the same file.
 
 ```ts
 // 🛑 this won't work
-@Component({...})
-class GreetingsComponent {}
+@Component({ ... })
+class GreetingsComponent {
+}
 
-test('<jc-greetings>', async ({ mount }) => {
+test('should work', async ({ mount }) => {
   await mount(GreetingsComponent);
 });
 ```
 
-### ...pass any symbol other than a component class
-This makes the following impossible:
-- passing providers to the `mount()` function
-- passing modules to the `mount()` function (this is what currently makes the usage of mounting templates impossible)
-- use non-standalone components
-
-### ...use non-[Versatile Angular Style](https://marmicode.io/blog/versatile-angular)
-We'll need a vite plugin to support traditional DI, external templates and stylesheets etc...
-
-## 🔮 Future workarounds
+# 📦 Setup
 
-If you really can't make it to [Versatile Angular Style](https://marmicode.io/blog/versatile-angular),
-we can think of a couple of workarounds like using a vite plugin like **Brandon Roberts' [vite-plugin-angular](https://github.com/analogjs/analog/tree/main/packages/vite-plugin-angular)**
-
-We could also implement some custom transform that registers the providers and import modules, like Playwright does for the component class.
-
-# Setup
-
-## 📦 Install
+### 1. Install
 
 ```sh
 # You can run this command in an existing workspace.
-yarn create playwright --ct # or npm init playwright@latest -- --ct
+npm create playwright -- --ct
 
 # Choose React
 
@@ -259,28 +275,46 @@ yarn create playwright --ct # or npm init playwright@latest -- --ct
 #  svelte
 #  solid
 
-yarn add -D @jscutlery/playwright-ct-angular @playwright/test # or npm install -D @jscutlery/playwright-ct-angular @playwright/test
+npm add -D @jscutlery/playwright-ct-angular @jscutlery/swc-angular unplugin-swc
+npm uninstall -D @playwright/experimental-ct-react
 ```
 
-## 🛠 Configure
+### 2. Configure
+
+- Update `playwright-ct.config.ts` and replace:
 
-Update `playwright-ct-config.ts` and replace:
 ```ts
-import type { PlaywrightTestConfig } from '@playwright/experimental-ct-react';
-import { devices } from '@playwright/experimental-ct-react';
+import { defineConfig, devices } from '@playwright/experimental-ct-react';
 ```
 
 with
 
 ```ts
-import type { PlaywrightTestConfig } from '@jscutlery/playwright-ct-angular';
-import { devices } from '@jscutlery/playwright-ct-angular';
+import { defineConfig, devices } from '@jscutlery/playwright-ct-angular';
+import { swcAngularUnpluginOptions } from '@jscutlery/swc-angular'
+import swc from 'unplugin-swc';
+```
+
+- Configure vite plugin:
+
+```ts
+export default defineConfig({
+  use: {
+    // ...
+    ctViteConfig: {
+      // ...
+      plugins: [
+        swc.vite(swcAngularUnpluginOptions())
+      ]
+    }
+  }
+});
 ```
 
-### Change tests extension
+### 3. Change tests extension
 
 In order to avoid collisions with other tests (e.g. Jest / Vitest),
-We can replace the default matching extension `.spec.ts` with `.pw.ts`:
+You can replace the default matching extension `.spec.ts` with `.pw.ts`:
 
 ```ts
 const config: PlaywrightTestConfig = {

package/{src/register.d.ts → cli.js}

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * Copyright (c) Microsoft Corporation.
  *
@@ -5,7 +6,7 @@
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
@@ -13,5 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-declare const _default: (components: any) => void;
-export default _default;
+
+const { program } = require('@playwright/experimental-ct-core/lib/program');
+
+program.parse(process.argv);

package/hooks.cjs.js

@@ -2,31 +2,16 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-/**
- * Copyright (c) Microsoft Corporation.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
 const __pw_hooks_before_mount = [];
 const __pw_hooks_after_mount = [];
 window['__pw_hooks_before_mount'] = __pw_hooks_before_mount;
 window['__pw_hooks_after_mount'] = __pw_hooks_after_mount;
-const beforeMount = (callback) => {
+function beforeMount(callback) {
     __pw_hooks_before_mount.push(callback);
-};
-const afterMount = (callback) => {
+}
+function afterMount(callback) {
     __pw_hooks_after_mount.push(callback);
-};
+}
 
 exports.afterMount = afterMount;
 exports.beforeMount = beforeMount;

package/hooks.esm.js

@@ -1,27 +1,12 @@
-/**
- * Copyright (c) Microsoft Corporation.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
 const __pw_hooks_before_mount = [];
 const __pw_hooks_after_mount = [];
 window['__pw_hooks_before_mount'] = __pw_hooks_before_mount;
 window['__pw_hooks_after_mount'] = __pw_hooks_after_mount;
-const beforeMount = (callback) => {
+function beforeMount(callback) {
     __pw_hooks_before_mount.push(callback);
-};
-const afterMount = (callback) => {
+}
+function afterMount(callback) {
     __pw_hooks_after_mount.push(callback);
-};
+}
 
 export { afterMount, beforeMount };

package/index.cjs.js

@@ -2,11 +2,9 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var mount = require('@playwright/experimental-ct-core/lib/mount');
-var playwright = require('@playwright/test');
-var jestMock = require('jest-mock');
-var experimentalCtCore = require('@playwright/experimental-ct-core');
-var path = require('path');
+var path = require('node:path');
+var playwrightCtCore = require('@playwright/experimental-ct-core');
+var test$1 = require('@playwright/test');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -26,87 +24,44 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var playwright__namespace = /*#__PURE__*/_interopNamespace(playwright);
 var path__namespace = /*#__PURE__*/_interopNamespace(path);
+var playwrightCtCore__namespace = /*#__PURE__*/_interopNamespace(playwrightCtCore);
 
-const mountTest = playwright__namespace.test.extend(mount.fixtures);
-const test = mountTest.extend({
-    /**
-     * Override mount to return output spies and enjoy type inference.
-     * This allows this:
-     *
-     * const { spies } = mount(..., {outputs: {citySelect: jest.fn()}})
-     *
-     * instead of this:
-     *
-     * const citySelectSpy: jest.MockedFunction<(city: string) => void> = jest.fn();
-     * mount(..., {outputs: {citySelect: citySelectSpy}});
-     *
-     * @hack we are willingly not using `async mount(...)` syntax here
-     * because it would be transpiled to `_async(function mount() { ... }`
-     * by Nx's default rollout config.
-     * Playwright dynamically parses the given function so converting
-     * async / await to a wrapped function would simply break the library causing
-     * a `TypeError: mount is not a function` error.
-     */
-    mount({ mount, page }, use) {
-        return use(async (component, options = {}) => {
-            /* 1. Create a spy for each output in `spyOutputs`... */
-            const spies = options.spyOutputs?.reduce((acc, key) => {
-                return {
-                    ...acc,
-                    [key]: jestMock.fn(),
-                };
-            }, {}) ?? {};
-            /* 2. ...then use it as an output... */
-            await mount(component, {
-                ...options,
-                outputs: {
-                    ...options.outputs,
-                    ...spies,
-                },
-            });
-            /* Grab a locator to the TestBed's root element.
-             * We are loading a fresh new page for each test
-             * so the id should always be "root0".
-             * Otherwise, we'd have to hack our way and somehow grab all
-             * the `#root*`, sort them and grab the last one.
-             * As a matter of fact, we can't grab a reference to the fixture. */
-            const locator = page.locator('#root0');
-            /* Add spies to the returned locator. */
-            return Object.assign(locator, { spies });
-        });
-    },
-});
-const expect = playwright__namespace.expect;
-const devices = playwright__namespace.devices;
-
-/**
- * Copyright (c) Microsoft Corporation.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-function plugin() {
-    /* Only fetch upon request to avoid resolution in workers. */
-    const { createPlugin,
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-     } = require('@playwright/experimental-ct-core/lib/vitePlugin');
-    // eslint-disable-next-line @typescript-eslint/no-empty-function
-    return createPlugin(path__namespace.join(__dirname, 'register-source.mjs'), () => { });
-}
-const defineConfig = (config) => experimentalCtCore.defineConfig({ ...config, _plugins: [plugin] });
+/* @hack `test` is not exported in the type definition of `@playwright/experimental-ct-core`. */
+// @eslint-disable-next-line @typescript-eslint/no-explicit-any
+const test = playwrightCtCore__namespace.test;
+const defineConfig = (config, ...configs) => {
+    const original = playwrightCtCore__namespace.defineConfig({
+        ...config,
+        '@playwright/test': {
+            packageJSON: require.resolve('./package.json'),
+        },
+        '@playwright/experimental-ct-core': {
+            registerSourceFile: path__namespace.join(__dirname, 'register-source.mjs'),
+        },
+    }, ...configs);
+    /* @hack for some weird reason, if we do not require the babel plugin here,
+     * babel loads an empty object instead of the default exported function. */
+    require('@jscutlery/playwright-ct-angular/transform-angular');
+    return {
+        ...original,
+        '@playwright/test': {
+            ...original['@playwright/test'],
+            babelPlugins: [
+                ...original['@playwright/test'].babelPlugins,
+                [require.resolve('@jscutlery/playwright-ct-angular/transform-angular')],
+            ],
+        },
+    };
+};
 
+Object.defineProperty(exports, 'devices', {
+  enumerable: true,
+  get: function () { return test$1.devices; }
+});
+Object.defineProperty(exports, 'expect', {
+  enumerable: true,
+  get: function () { return test$1.expect; }
+});
 exports.defineConfig = defineConfig;
-exports.devices = devices;
-exports.expect = expect;
 exports.test = test;