@genesislcap/foundation-testing 14.408.0 → 14.409.0-FUI-2495.2

package/README.md

@@ -1,294 +1,21 @@
-# Genesis Foundation testing
+# @genesislcap/foundation-testing
 
-[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)
-[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
+Documentation for this package is published on the Genesis docs site:
 
-`foundation-testing` provides shared unit and e2e testing functionality.
-
-## Unit Testing
-
-The foundation-testing package is a comprehensive framework for implementing Unit Tests. Use it to ensure that your Genesis Web Application provides a seamless user experience by testing components, functions and user interactions across various scenarios.
-
-### **Key Tools and Features:**
-
-- **Customizable Unit Test Suites**: Manage and create detailed test suites in the **tests/unit** folder, focusing on critical components and functions. These test suites are fully customizable by default, so you can cover all different parts of the application.
-- **Sinon integration**: Use Sinon.JS to incorporate test spies, stubs and mocks into your Unit Tests.
-- **Very lightweight**: The test framework provided by foundation-testing is very lightweight and contains [minimal dependencies](https://npm.anvaka.com/#/view/2d/uvu).
-- **Extremely performant**: Much faster than competing test runners, see [benchmarks](https://github.com/lukeed/uvu/tree/master#benchmarks).
-- **Individually executable test files**: You can keep your tests suites organized by splitting them into multiple files (optional). 
-- **Browser-compatible**: You can easily run and debug your tests in a browser environment, which allows you to use browser developer tools.
-
-### **Getting Started with Unit Testing:**
-
-- Define test suites in the **tests/unit** folder, targeting critical components and functions.
-- Use UVU for fast and lightweight Unit Testing.
-- Use Sinon.JS if you need spies, stubs or mocks.
-- Execute tests locally or on your CI pipeline, ensuring reliable and consistent outcomes.
-
-## E2E Testing
-
-The foundation-testing package is a comprehensive framework for implementing End-to-End (E2E) testing. use it to ensure that your Genesis Web Application provides a seamless user experience by testing workflows and user interactions across various scenarios.
-
-### **Key Tools and Features:**
-
-- **Customizable E2E scenarios**: Manage and create detailed test scenarios within the **tests/e2e** folder, focusing on critical user journeys. These scenarios are fully customizable by default, allowing for comprehensive coverage of different user paths and interactions.
-- **Playwright integration**: Use Playwright to automate browser actions, simulate user interactions, and verify that your application behaves as expected across different browsers. Playwright supports cross-browser testing, parallel test execution, and context isolation, allowing for robust and scalable E2E tests. Playwright can capture videos, screenshots, and other artifacts when a test fails, aiding in debugging and issue resolution.
-- **Lighthouse performance testing**: Integrate Lighthouse to measure and improve the performance, accessibility, SEO, and overall quality of your web applications. Use Lighthouse reports to track key performance metrics, such as load time, interactivity, and visual stability, and enforce performance budgets to maintain a high standard for user experience.
-- **Automated testing pipeline**: Integrate your E2E tests into a continuous integration (CI) pipeline, ensuring that every change to the codebase is thoroughly tested before deployment. This automation reduces the risk of bugs and ensures consistent test outcomes across different environments.
-
-### **Getting Started with E2E Testing:**
-
-1. **Creating and running E2E Tests**:
-   - Define test scenarios in the **tests/e2e** folder, targeting critical user journeys and application functionalities.
-   - Use Playwright for browser automation and Lighthouse for performance auditing within the same test suite.
-   - Execute tests via your preferred test runner or CI pipeline, ensuring reliable and consistent outcomes.
-2. **Using Playwright**:
-   - Install and configure Playwright as part of your project dependencies. Follow the set-up guide provided by the foundation-testing package.
-   - Write and run tests using the Playwright API to simulate real-world user interactions. These include clicking buttons, filling in forms, and navigating from page to page.
-3. **Incorporating Lighthouse**:
-   - Integrate Lighthouse into your E2E tests to run performance audits alongside functional tests.
-   - Use the insights from Lighthouse reports to identify and address performance issues, optimizing your application for speed and user experience.
-4. **Advanced features**:
-   - **BDD Testing**: Write behavior-driven tests using `playwright-bdd`, making it easier to define test scenarios and expectations in a human-readable format.
-   - **Cross-Browser Testing**: Use the Playwright cross-browser support to ensure your application works seamlessly across different browsers, including Chrome, Firefox, and WebKit.
-   - **Visual Testing**: Use the Playwrights screenshot and visual comparison features to validate the consistency of your UI across different devices and resolutions.
-   - **Performance Budgets**: Set performance thresholds using Lighthouse to maintain high performance standards, ensuring metrics like Time to Interactive (TTI) and First Contentful Paint (FCP) stay within acceptable limits.
-
-## Test Organisation
-
-You can unit-test specific logic by adding a test file alongside the source file.
-
-```ts
-logic.ts
-logic.test.ts
-```
-
-If your test spans more than one file or is more of an end-to-end test, you may wish to add your test to your package's **/test** directory instead. An example structure might be:
-
-```plaintext
-├── src
-│   └── logic.ts
-│   └── logic.test.ts
-│   └── component.ts
-│   └── component.test.ts
-├── test
-│   └── e2e
-│       └── baseline.e2e.ts
-│   └── unit
-│       └── baseline.test.ts
-├── package.json
-└── playwright.config.ts
-```
-
-The contents of your package's **playwright.config.ts** may include:
-
-```ts
-export { configDefaults as default } from '@genesislcap/foundation-testing/e2e';
-```
-
-If you need to customise configuration, you can do it as follows:
-
-```ts
-import { configDefaults } from '@genesislcap/foundation-testing/e2e';
-
-export default {
-  ...configDefaults,
-  // Any custom configuration here e.g. disabling the web server:
-  webServer: undefined,
-};
-```
-
-If you need to customise JSDOM, you can create a **jsdom.setup.ts** file in your package directory:
-
-```ts
-// custom code
-export * from '@genesislcap/foundation-testing/jsdom';
-```
-
-## Test scripts
-
-The test-related scripts to add to your package's **package.json** file may include:
-
-```json
-"test": "genx test",
-"test:single": "genx test --match connect.test.ts",
-"test:single:browser": "genx test --browser --match connect.test.ts",
-"test:single:browser:raw-match": "genx test --browser --raw-match --match ./**/connect.test.ts",
-"test:select": "genx test --match '(connect|reconnectStrategy|kv).test.ts'",
-"test:select:browser": "genx test --browser --match '(connect|reconnectStrategy|kv).test.ts'",
-"test:glob": "genx test --match reconnectStrategy*.test.ts",
-"test:glob:browser": "genx test --browser --match reconnectStrategy*.test.ts",
-"test:coverage": "genx test --coverage",
-"test:coverage:browser": "genx test --coverage --browser",
-"test:e2e": "genx test --e2e",
-"test:e2e:debug": "genx test --e2e --debug",
-"test:e2e:ui": "genx test --e2e --interactive",
-"test:unit:browser": "genx test --browser",
-"test:unit:browser:watch": "genx test --browser --watch",
-"test:unit:watch": "genx test --watch",
-"test:debug": "genx test --debug"
-```
-
-## Testing logic
-
-The **logic.test.ts** usually uses `createLogicSuite`, which is used to test function output given certain input
-arguments. Based on user feedback, these arguments are now passed as an array by convention:
-
-```ts
-// logic.test.ts
-import { createLogicSuite } from '@genesislcap/foundation-testing';
-import { myFunction } from './logic';
-
-const Suite = createLogicSuite('myFunction');
-Suite('myFunction should provide expected results', ({ runCases }) => {
-  runCases(myFunction, [
-    [['1'], true],
-    [[123], true],
-    [['60%'], true],
-    [['$60'], false],
-    [['1.1'], false],
-    [[''], false],
-    [[true], false],
-    [[null], false],
-    [[undefined], false],
-  ]);
-});
-
-Suite.run();
-```
-
-## Testing components
-
-The **component.test.ts** or any test that directly or indirectly makes use of the DI uses `createComponentSuite`. Apart from setting up and tearing down your element fixture with a wrapping design system and DI container, this util also allows you to provide DI container mocks, which are required for certain testing flows.
-
-```ts
-// component.test.ts
-import { Connect } from '@genesislcap/foundation-comms';
-import { ConnectMock } from '@genesislcap/foundation-comms/testing';
-import { assert, createComponentSuite, Registration } from '@genesislcap/foundation-testing';
-import { MyComponent } from './component';
-
-/**
- * As we're using tag name in the Suite, we hold a reference to avoid tree shaking.
- */
-MyComponent;
-
-/**
- * Create mock
- */
-const connectMock = new ConnectMock();
-connectMock.nextMetadata = {
-  FIELD: [
-    {
-      NAME: 'foo',
-      TYPE: 'bar',
-    },
-  ],
-};
-
-/**
- * Resister mock instance
- */
-const mocks = [Registration.instance(Connect, connectMock)];
-
-const Suite = createComponentSuite<MyComponent>(
-  'MyComponent',
-  'my-component', // < or () => myComponent() if your component is composeable
-  null,
-  mocks,
-);
-
-Suite('Can be created in the DOM', async ({ element }) => {
-  assert.ok(element);
-});
-
-Suite('Connect is mocked in the container', async ({ container }) => {
-  const serviceMock = container.get(Connect);
-  assert.instance(serviceMock, ConnectMock);
-});
-
-Suite('Attr changes update internals as expected', async ({ element }) => {
-  element.setAttribute('resource-name', 'ALL_USERS');
-  assert.match(element.optionsHash, /ALL_USERS/);
-  element.setAttribute('order-by', 'USERNAME');
-  assert.match(element.optionsHash, /USERNAME/);
-});
-
-Suite('Connect.getMetadata returns expected nextMetadata', async ({ container }) => {
-  const serviceMock = container.get(Connect) as ConnectMock;
-  /**
-   * Assert base case
-   */
-  let serviceMeta = await serviceMock.getMetadata('someResource');
-  assert.is(serviceMeta.FIELD[0].NAME, 'foo');
-  /**
-   * Apply next and assert
-   */
-  const metadata = {
-    FIELD: [
-      {
-        NAME: 'hello',
-        TYPE: 'world',
-      },
-    ],
-  };
-  serviceMock.nextMetadata = {
-    ...metadata,
-  };
-  serviceMeta = await serviceMock.getMetadata('someResource');
-  assert.equal(serviceMeta, {
-    ...metadata,
-  });
-  // TODO: Trigger and cross check component reactions to underlying data changes
-});
-
-Suite.run();
-```
-
-## Testing E2E
-
-The **baseline.e2e.ts** uses `playwright`; test cases have access to the fixtures provided during set-up.
-
-```ts
-import { test, expect } from '@genesislcap/foundation-testing/e2e';
-
-test('baseline test', async ({ page }) => {
-    await page.goto('https://playwright.dev/');
-    const name = await page.innerText('.navbar__title');
-    expect(name).toBe('Playwright');
-});
-```
-
-_We will be adding more details on E2E in future updates._
+**Docs: [Testing](https://docs.genesis.global/docs/develop/client-capabilities/testing/)**
 
 ## Installation
 
-To enable this module in your application, follow the steps below.
-
-1. Add `@genesislcap/foundation-testing` as a dependency in your `package.json` file. Whenever you change the dependencies of your project, ensure you run the `$ npm run bootstrap` command again. You can find more information in the [package.json basics](https://learn.genesis.global/secure/web/basics/package-json-basics/) page.
+Add the package to your `package.json` dependencies. After changing dependencies, run `npm run bootstrap` (or your project's equivalent). See [package.json basics](https://learn.genesis.global/secure/web/basics/package-json-basics/) for more information.
 
 ```json
 {
   "dependencies": {
     "@genesislcap/foundation-testing": "latest"
-  },
+  }
 }
 ```
 
-### **Unit Testing Resources and Further Documentation:**
-
-- [UVU](ttps://github.com/lukeed/uvu)
-- [Sinon.JS](https://sinonjs.org/releases/v18/)
-
-### **E2E Resources and Further Documentation:**
-
-- [foundation-testing](https://github.com/genesislcap/foundation-ui/tree/master/packages/foundation/foundation-testing)
-- [Playwright Documentation](https://playwright.dev/)
-- [playwright-bdd](https://github.com/vitalets/playwright-bdd)
-- [Lighthouse Documentation](https://developers.google.com/web/tools/lighthouse) 
-
-## [API Docs](./docs/api/index.md)
-
 ## License
 
 Note: this project provides front-end dependencies and uses licensed components listed in the next section; thus, licenses for those components are required during development. Contact [Genesis Global](https://genesis.global/contact-us/) for more details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-testing",
   "description": "Genesis Foundation Testing",
-  "version": "14.408.0",
+  "version": "14.409.0-FUI-2495.2",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -54,11 +54,10 @@
   },
   "scripts": {
     "api:extract": "api-extractor run --local",
-    "api:document": "api-documenter markdown -i dist -o docs/api",
-    "build": "npm run clean && tsc -b ./tsconfig.json && tsc -b ./tsconfig.cjs.json && npm run api:extract && npm run api:document",
+    "build": "npm run clean && tsc -b ./tsconfig.json && tsc -b ./tsconfig.cjs.json && npm run api:extract",
     "circular": "npx -y madge --extensions ts --circular ./src",
     "clean": "rimraf dist temp tsconfig.tsbuildinfo",
-    "dev": "tsc -b ./tsconfig.json -w",
+    "dev": "genx dev -b ts",
     "test": "uvu -r tsx/cjs -r ./src/jsdom/setup.ts . test.ts",
     "lint": "genx lint --profile",
     "lint:fix": "genx lint --fix"
@@ -76,7 +75,7 @@
     "tsx": "^4.7.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "14.408.0",
+    "@genesislcap/foundation-logger": "14.409.0-FUI-2495.2",
     "@microsoft/fast-element": "1.14.0",
     "@microsoft/fast-foundation": "2.50.0",
     "@playwright/test": "^1.54.2",
@@ -96,5 +95,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "26b08831fd001b4ee95c8a0d3364a18c0ec4005b"
+  "gitHead": "1fcaf08e9b7559024b25dc6ccc27e3bc62f1512b"
 }

package/docs/api/foundation-testing.componentcontext.container.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [ComponentContext](./foundation-testing.componentcontext.md) &gt; [container](./foundation-testing.componentcontext.container.md)
-
-## ComponentContext.container property
-
-**Signature:**
-
-```typescript
-container: Container;
-```

package/docs/api/foundation-testing.componentcontext.designsystem.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [ComponentContext](./foundation-testing.componentcontext.md) &gt; [designSystem](./foundation-testing.componentcontext.designsystem.md)
-
-## ComponentContext.designSystem property
-
-**Signature:**
-
-```typescript
-designSystem: DesignSystem;
-```

package/docs/api/foundation-testing.componentcontext.md

@@ -1,91 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [ComponentContext](./foundation-testing.componentcontext.md)
-
-## ComponentContext interface
-
-Component suite context interface
-
-**Signature:**
-
-```typescript
-export interface ComponentContext<TElement = HTMLElement> extends Pick<Fixture<TElement>, 'element' | 'disconnect'> 
-```
-**Extends:** Pick&lt;[Fixture](./foundation-testing.fixture.md)<!-- -->&lt;TElement&gt;, 'element' \| 'disconnect'&gt;
-
-## Properties
-
-<table><thead><tr><th>
-
-Property
-
-
-</th><th>
-
-Modifiers
-
-
-</th><th>
-
-Type
-
-
-</th><th>
-
-Description
-
-
-</th></tr></thead>
-<tbody><tr><td>
-
-[container](./foundation-testing.componentcontext.container.md)
-
-
-</td><td>
-
-
-</td><td>
-
-Container
-
-
-</td><td>
-
-
-</td></tr>
-<tr><td>
-
-[designSystem](./foundation-testing.componentcontext.designsystem.md)
-
-
-</td><td>
-
-
-</td><td>
-
-DesignSystem
-
-
-</td><td>
-
-
-</td></tr>
-<tr><td>
-
-[runCases](./foundation-testing.componentcontext.runcases.md)
-
-
-</td><td>
-
-
-</td><td>
-
-[RunCases](./foundation-testing.runcases.md)
-
-
-</td><td>
-
-
-</td></tr>
-</tbody></table>
-

package/docs/api/foundation-testing.componentcontext.runcases.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [ComponentContext](./foundation-testing.componentcontext.md) &gt; [runCases](./foundation-testing.componentcontext.runcases.md)
-
-## ComponentContext.runCases property
-
-**Signature:**
-
-```typescript
-runCases: RunCases;
-```

package/docs/api/foundation-testing.createcomponentsuite.md

@@ -1,168 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-testing](./foundation-testing.md) &gt; [createComponentSuite](./foundation-testing.createcomponentsuite.md)
-
-## createComponentSuite() function
-
-Create component test suite.
-
-**Signature:**
-
-```typescript
-export declare function createComponentSuite<TElement = HTMLElement>(title: string, elementNameOrGetter: string | ElementGetter, context?: ComponentContext<TElement>, registrations?: Registration<any>[]): uvu.Test<ComponentContext<TElement>>;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-
-</th><th>
-
-Type
-
-
-</th><th>
-
-Description
-
-
-</th></tr></thead>
-<tbody><tr><td>
-
-title
-
-
-</td><td>
-
-string
-
-
-</td><td>
-
-Title of the test suite
-
-
-</td></tr>
-<tr><td>
-
-elementNameOrGetter
-
-
-</td><td>
-
-string \| [ElementGetter](./foundation-testing.elementgetter.md)
-
-
-</td><td>
-
-Element tag name or getter which is used to create the element within the fixture
-
-
-</td></tr>
-<tr><td>
-
-context
-
-
-</td><td>
-
-[ComponentContext](./foundation-testing.componentcontext.md)<!-- -->&lt;TElement&gt;
-
-
-</td><td>
-
-_(Optional)_ Optional component context [ComponentContext](./foundation-testing.componentcontext.md)
-
-
-</td></tr>
-<tr><td>
-
-registrations
-
-
-</td><td>
-
-Registration&lt;any&gt;\[\]
-
-
-</td><td>
-
-_(Optional)_ Optional array of DI container registrations
-
-
-</td></tr>
-</tbody></table>
-
-**Returns:**
-
-uvu.Test&lt;[ComponentContext](./foundation-testing.componentcontext.md)<!-- -->&lt;TElement&gt;&gt;
-
-The test suite
-
-## Remarks
-
-Used to test function output given certain input arguments.
-
-## Example 1
-
-Simple suite using the tag name of the component.
-
-```ts
-import { createComponentSuite } from '@genesislcap/foundation-testing';
-import { Component } from './component';
-Component; // < As we're using tag name in the Suite, we hold a reference to avoid tree shaking.
-const Suite = createComponentSuite<Component>('Component', 'my-component');
-// test cases...
-Suite.run();
-```
-
-## Example 2
-
-Mocking a DI dependency for a composable component.
-
-```ts
-const connectMock = new ConnectMock();
-const mocks = [Registration.instance(Connect, connectMock)];
-const Suite = createComponentSuite<ConnectionIndicator>('ConnectionIndicator Component', () => connectionIndicator(), null, mocks);
-// test cases...
-Suite.run();
-```
-
-## Example 3
-
-An element will be required to test anything that directly or in-directly makes use of the DI container, for example, a service that can be injected into components, or has its own injected dependencies.
-
-```ts
-import { Service } from './service';
-@customElement({
-  name: 'test-element',
-  template: html`<slot></slot>`,
-})
-class TestElement extends FASTElement {}
-const mocks = [...];
-const Suite = createComponentSuite<TestElement>('Service', 'test-element', null, mocks);
-// test cases...
-Suite.run();
-```
-Importing the service should invoke the Service's DI registration, so in your test cases you can simply query the container to get a reference to your service.
-
-```ts
-Suite('Service.x does something expected', async ({ container }) => {
-  const myService = container.get(Service);
-  // assert
-});
-```
-You can optionally add the service to the test element for lookup convenience, but this is not required.
-
-```ts
-class TestElement extends FASTElement {
-  @Service service: Service;
-}
-Suite('Element has service injected', async ({ element }) => {
-  assert.ok(element.service);
-});
-```
-