chore(wtr): make readme helpful @W-19098307 (#5547)

* chore(wtr): make readme helpful

* test(wtr): oops can't mock modules

* test(wtr): it doesn't log in production

* docs(wtr): use JSDoc in code instead of forgettable README

Author: wjhsf

package.json

@@ -23,10 +23,8 @@
         "test:bespoke": "nx run-many --target=test",
         "test:debug": "vitest --inspect-brk --no-file-parallelism",
         "test:ci": "vitest run --coverage",
-        "test:karma": "nx test @lwc/integration-karma",
-        "test:karma:start": "nx start @lwc/integration-karma",
-        "test:hydration": "nx hydration:test @lwc/integration-karma",
-        "test:hydration:start": "nx hydration:start @lwc/integration-karma",
+        "test:wtr": "nx test @lwc/integration-not-karma",
+        "test:hydration": "nx test:hydration @lwc/integration-not-karma",
         "test:integration": "nx sauce @lwc/integration-tests",
         "test:performance": "nx test @lwc/perf-benchmarks",
         "test:performance:best": "nx test:best @lwc/perf-benchmarks",

packages/@lwc/integration-not-karma/README.md

@@ -1,3 +1,36 @@
-# @lwc/integration-not-karma
+# LWC [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) integration tests
 
-It's not karma, it's something else!
+## Quick Start
+
+To run integration tests, run `yarn test:wtr` from the monorepo root, or `yarn test` from the package directory.
+
+To run hydration tests, run `yarn test:hydration` from either the monorepo root or the package directory.
+
+To manually debug tests in your browser, add the `--manual` flag to the test command.
+
+To run individual test files, provide them as CLI arguments. If using relative paths, they must be relative to the _package directory_, e.g. `yarn test:wtr test/act/index.spec.js`.
+
+Environment variables are used as controls to run tests in different modes (e.g native vs synthetic shadow, different API versions). The full list of controls is defined in [`helpers/options.js`](./helpers/options.js).
+
+## Architecture
+
+- `configs`: WTR configuration files. The main entrypoints are `integration.js` and `hydration.js`.
+- `helpers`: Helper functions used by tests and the test runner.
+- `mocks`: Module mocks to replace imports in tests.
+- `test`: The test directory for integration tests.
+- `test-hydration`: The test directory for hydration tests.
+
+### Integration Tests
+
+Integration tests are simply `.spec.js` files that run in the browser. LWC components are transformed by a plugin defined in `serve-integration.js`.
+
+### Hydration Tests
+
+Hydration tests test the SSR packages, and are therefore more complex than the integration tests. While the files are named `index.spec.js`, they are actually _config_ files. The actual test executed is defined in `test-hydration.js`, which also contains the interface definition for the config. Each hydration test is also expected to define an entrypoint component named `x/main`. The hydration tests are transformed by a plugin defined in `serve-hydration.js`.
+
+## Design Goals
+
+1. Web Test Runner is an ESM-first test runner, which means that as much code as possible should be served directly to the browser. LWC components must be transformed, so some bundling is unavoidable, but should be minimized.
+2. "Magic" should be avoided as much as possible -- global variables, code defined in strings, etc. When unavoidable, the source of the magic should be explained in comments.
+3. Simplify code wherever possible. These tests were originally written many years ago, for a different testing framework (Karma). There are many workarounds or sub-optimal patterns used to accommodate Karma or older browsers, because new developers were unfamiliar with established patterns, and so on. When updating tests, we should try to update the code to remove legacy logic.
+4. Over-use code comments. There are a lot of systems in play, and it's not always apparent why code was written in a particular way.

packages/@lwc/integration-not-karma/configs/integration.js

@@ -16,6 +16,7 @@ export default {
     files: ['test/**/*.spec.js', '!test/custom-elements/index.spec.js'],
     plugins: [
         ...baseConfig.plugins,
+        // Only used for the `sanitizeAttribute` test
         importMapsPlugin({ inject: { importMap: { imports: { lwc: './mocks/lwc.js' } } } }),
         testPlugin,
     ],

packages/@lwc/integration-not-karma/configs/plugins/test-hydration.js

@@ -2,6 +2,75 @@ import { spyOn } from '@vitest/spy';
 import * as LWC from 'lwc';
 import { setHooks } from '../../helpers/hooks';
 
+/*
+ * Because these tests are written in JS, the type defs below are not enforced. They are provided
+ * solely as documentation. They can be used as IDE autocomplete if the test configs are annotated
+ * with the JSDoc below (the number of ../ may need to be adjusted):
+ /** @type {import('../../../configs/plugins/test-hydration.js').HydrationTestConfig} */
+
+/**
+ * @typedef {object} TestConfig
+ *   Exactly one of `test` or `advancedTest` must be defined. All other properties are optional.
+ *   `snapshot` is ignored if `advancedTest` is defined.
+ * @property {Record<string, string>} [props]
+ *   Props to provide for the root test component.
+ * @property {Record<string, string} [clientProps]
+ *   Client-side props to hydrate the root test component.
+ * @property {string[]} [requiredFeatureFlags]
+ *   List of feature flags that should be enabled for the test.
+ * @property {SnapshotFunc} [snapshot]
+ *   A function that can be used to capture the pre-hydration state of the page.
+ *   Only used if `test` is defined.
+ * @property {TestFunc} [test]
+ *   A function that contains assertions, run after hydration.
+ *   Should be used if asserting the pre-hydration state is not required.
+ * @property {AdvancedTestFunc} [advancedTest]
+ *   A function that contains assertions and is also responsible for hydrating the page.
+ *   Should only be used if assertions are required before hydration.
+ */
+
+/**
+ * @callback SnapshotFunc
+ *   Captures a snapshot of the page before hydration.
+ * @param {HTMLElement} component
+ *   The root test component, corresponding to the `x-main` component.
+ * @returns {unknown}
+ *   Any data required for test assertions.
+ */
+
+/**
+ * @callback TestFunc
+ *   Asserts the state of the page after hydration has occurred.
+ * @param {HTMLElement} target
+ *   The root test element, corresponding to the `x-main` component.
+ * @param {unknown} snapshot
+ *   The result of the `snapshot` function, if defined.
+ * @param {Record<'log' | 'warn' | 'error', unknown[][]>} calls
+ *   Console calls that occurred during hydration.
+ * @returns {void}
+ */
+
+/**
+ * @callback AdvancedTestFunc
+ *   Asserts the state of the page before and after hydration has occurred.
+ *   Is responsible for calling `hydrateComponent`.
+ * @param {HTMLElement} target
+ *   The root test element, corresponding to the `x-main` component.
+ * @param {object} utils
+ *   Various things helpful for making assertions.
+ * @param {import('lwc').LightningElement} utils.Component
+ *   The constructor for the root test component (`x-main`).
+ * @param {import('lwc').hydrateComponent} utils.hydrateComponent
+ *   A bound instance of `hydrateComponent`. Must be called for tests to pass.
+ * @param {Record<'log' | 'warn' | 'error', unknown[][]> & {reset: () => void}} utils.consoleSpy
+ *   A spy on `console` to track calls. Calling `reset` empties the tracked calls.
+ * @param {HTMLDivElement} utils.container
+ *   The parent of the test root element.
+ * @param {'x-main'} utils.selector
+ *   The selector of the root test element.
+ * @returns {void}
+ */
+
 setHooks({ sanitizeHtmlContent: (content) => content });
 
 function parseStringToDom(html) {
@@ -86,13 +155,21 @@ export function runTest(configPath, componentPath, ssrRendered) {
             target = container.querySelector(selector);
             await testConfig.test(target, snapshot, consoleSpy.calls);
         } else if (testConfig.advancedTest) {
+            let hydrated = false;
+            // We can't spy on LWC because it's an ESM module, so we just wrap it
+            const hydrateComponent = (...args) => {
+                hydrated = true;
+                return LWC.hydrateComponent(...args);
+            };
             await testConfig.advancedTest(target, {
                 Component,
-                hydrateComponent: LWC.hydrateComponent.bind(LWC),
+                hydrateComponent,
                 consoleSpy,
                 container,
                 selector,
             });
+            // Sanity check: if we've never hydrated then we haven't set up the test correctly
+            expect(hydrated).toBe(true);
         } else {
             throw new Error(`Missing test or advancedTest function in ${configPath}.`);
         }

packages/@lwc/integration-not-karma/helpers/options.js

@@ -6,30 +6,38 @@ import { HIGHEST_API_VERSION } from '@lwc/shared';
 
 // --- Boolean test flags --- //
 
+/** Run SauceLabs tests using only "legacy" browsers. */
 export const LEGACY_BROWSERS = Boolean(process.env.LEGACY_BROWSERS);
 
+/** Force tests to run in native shadow mode with synthetic shadow polyfill patches. */
 export const FORCE_NATIVE_SHADOW_MODE_FOR_TEST = Boolean(
     process.env.FORCE_NATIVE_SHADOW_MODE_FOR_TEST
 );
 
+/** Enable ARIA string reflection as a global polyfill. */
 export const ENABLE_ARIA_REFLECTION_GLOBAL_POLYFILL = Boolean(
     process.env.ENABLE_ARIA_REFLECTION_GLOBAL_POLYFILL
 );
 
+/** Disable synthetic shadow support at the compiler level. */
 export const DISABLE_SYNTHETIC_SHADOW_SUPPORT_IN_COMPILER = Boolean(
     process.env.DISABLE_SYNTHETIC_SHADOW_SUPPORT_IN_COMPILER
 );
 
+/** Set the compiler flag to disable static content optimization. */
 export const DISABLE_STATIC_CONTENT_OPTIMIZATION = Boolean(
     process.env.DISABLE_STATIC_CONTENT_OPTIMIZATION
 );
 
+/** Set the runtime flag to use the synthetic custom element lifecycle instead of native. */
 export const DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE = Boolean(
     process.env.DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE
 );
 
+/** Disable detached rehydation. I don't know what that means. */
 export const DISABLE_DETACHED_REHYDRATION = Boolean(process.env.DISABLE_DETACHED_REHYDRATION);
 
+/** Run hydration tests using `@lwc/engine-server` instead of SSR v2. */
 export const ENGINE_SERVER = Boolean(process.env.ENGINE_SERVER);
 
 // --- Test config --- //
@@ -42,10 +50,12 @@ export const ENGINE_SERVER = Boolean(process.env.ENGINE_SERVER);
 // NOTE: NATIVE_SHADOW is not defined here because integration/hydration have different defaults
 export const SHADOW_MODE_OVERRIDE = process.env.SHADOW_MODE_OVERRIDE;
 
+/** The API version to use for compiling and rendering components. */
 export const API_VERSION = process.env.API_VERSION
     ? parseInt(process.env.API_VERSION, 10)
     : HIGHEST_API_VERSION;
 
+/** The `NODE_ENV` to set for tests (at runtime, in the browser). */
 export const NODE_ENV_FOR_TEST = process.env.NODE_ENV_FOR_TEST || 'development';
 
 /** Unique directory name that encodes the flags that the tests were executed with. */
@@ -69,9 +79,15 @@ export const COVERAGE_DIR_FOR_OPTIONS =
 
 // --- CI config --- //
 
+/** Whether or not to report coverage. Currently unused. */
 export const COVERAGE = Boolean(process.env.COVERAGE);
+/** SauceLabs username. */
 export const SAUCE_USERNAME = process.env.SAUCE_USERNAME;
+/** SauceLabs access key. */
 export const SAUCE_ACCESS_KEY = process.env.SAUCE_ACCESS_KEY || process.env.SAUCE_KEY;
+/** SauceLabs tunnel ID. */
 export const SAUCE_TUNNEL_ID = process.env.SAUCE_TUNNEL_ID;
+/** Whether or not we're running in CI. */
 export const CI = Boolean(process.env.CI);
+/** The GitHub Actions run ID, set by GitHub. */
 export const GITHUB_RUN_ID = process.env.GITHUB_RUN_ID;

packages/@lwc/integration-not-karma/test-hydration/adjacent-text-and-comment-nodes/index.spec.js

@@ -1,3 +1,4 @@
+/** @type {import('../../configs/plugins/test-hydration.js').TestConfig} */
 export default {
     snapshot(target) {
         const span = target.shadowRoot.querySelector('span');

packages/@lwc/integration-not-karma/test-hydration/adjacent-text-nodes/index.spec.js

@@ -1,3 +1,4 @@
+/** @type {import('../../configs/plugins/test-hydration.js').TestConfig} */
 export default {
     props: {},
     snapshot(target) {

packages/@lwc/integration-not-karma/test-hydration/attributes/class/index.spec.js

@@ -1,3 +1,4 @@
+/** @type {import('../../../configs/plugins/test-hydration.js').TestConfig} */
 export default {
     snapshot(target) {
         const div = target.shadowRoot.querySelector('div');

packages/@lwc/integration-not-karma/test-hydration/attributes/expression/index.spec.js

@@ -1,3 +1,4 @@
+/** @type {import('../../../configs/plugins/test-hydration.js').TestConfig} */
 export default {
     clientProps: {
         foo: 'foo',

packages/@lwc/integration-not-karma/test-hydration/attributes/falsy-mismatch/index.spec.js

@@ -1,5 +1,6 @@
 import { expectConsoleCallsDev } from '../../../helpers/utils.js';
 
+/** @type {import('../../../configs/plugins/test-hydration.js').TestConfig} */
 export default {
     props: {
         isFalse: false,