test(quantic): first setup of playwright added in Quantic (#4597)

## [SFINT-5768](https://coveord.atlassian.net/browse/SFINT-5768)

### Intro
In this PR, we introduce the Playwright setup for the Quantic project,
allowing for automated E2E tests on Lightning Web Components (LWC) in
Salesforce. The Playwright structure here includes:

### Page Objects:
Page objects encapsulate component selectors and interactions, making
tests more modular and maintainable, in the proposed structure we have
common page objects and unique page objects.

The common page objects will be shared across all the Quantic E2E tests,
for example:

- `ConfigurationObject`: responsible of configuring the Quantic Example
page to initializes the test environment for a given test.
- `SearchObject`: responsible of performing a search and intercepting
the search requests in both the search use case and the insight use
case.
- `InsightObject`: responsible of performing the logic that is specific
to the insight use case, like for example waiting the initialization of
the Quantic Insight Interface.

A unique page object is an object that is specific to a given component,
like in this example the `PagerObject`

### Fixtures:
A Playwright fixture is a reusable setup that provides a consistent
environment for tests.

I created a base fixture called `quanticBase` that will be the base of
all the fixture we will create for each Quantic component, this base
fixture by default uses `ConfigurationObject`, `SearchObject` and
`InsightObject` page objects as these are always needed in any test.

Additionally each component will have his own fixtures that will extend
`quanticBase`, like for example in this example, the QuanticPager has
two fixtures `testSearch` and `testInsight`, two fixtures that provides
the setup to test the component in the search use case and the insight
use case respectively.

### Tests:

Following this structure, each Quantic component will now contain a new
folder called `e2e` that will contain the page object of the component,
the fixtures needed to test and the test spec.
Each component will have the following structure:
```
QuanticPager/
│
├── e2e/
│   ├── page-object.ts
│   ├── fixture.ts
│   └── quantic-pager.e2e.ts
├── __test__/
│   └── quantic-pager.unit.test.ts
│
├── QuanticPager.js
├── QuanticPager.html
├── QuanticPager.css
```
Each component will have the component logic, the unit tests and the E2E
in the same folder.

Jest Unit tests should focus on the following points: 

- Test component behaviour in isolation.
- Mock External Dependencies like the capabilities used from the
Headless library.
- Ensure the component renders the correct HTML based on its state and
input properties.
- Verify that component properties update correctly based on user
interactions or lifecycle events.
- Cover edge cases.

Playwright E2E tests should focus on the following points: 

- Test the essential paths that users take to achieve their goals using
a given component.
- Mimic actual user actions, such as clicking buttons, entering data and
navigation.
- Test interactions with external systems like our Coveo APIs and
analytics.



[SFINT-5768]:
https://coveord.atlassian.net/browse/SFINT-5768?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

---------

Co-authored-by: Frederic Beaudoin <[email protected]>
Co-authored-by: Simon Milord <[email protected]>
Co-authored-by: Etienne Rocheleau <[email protected]>

Author: 4 people

package-lock.json

@@ -13,4 +13,7 @@ package.xml
 **/__tests__/**
 **/testUtils/**/*
 
+# E2E tests
+**/e2e/**
+
 **/README.md

packages/quantic/.forceignore

@@ -44,6 +44,9 @@ force-app/main/default/staticresources/dompurify
 # Test Coverage & Report
 coverage
 reports
+/test-results/
+/playwright-report/
+/playwright/.cache/
 
 # Cypress artifacts
 .cache/
@@ -58,4 +61,4 @@ docs/out/*
 # Environment Variables
 .env
 
-.tmp
+.tmp

packages/quantic/.gitignore

@@ -0,0 +1,58 @@
+# Decision Record: Testing Strategy for Quantic
+
+- **Date**: 2024-11-06
+- **Status**: accepted
+
+## Context
+
+Our project involves testing Lightning Web Components (LWCs) to ensure quality and reliability. We have decided to use Jest for unit testing to verify component logic and isolated behavior and Playwright for end-to-end (E2E) testing to validate user interactions and integration within the full UI. This document outlines the criteria for deciding what should be tested in each environment.
+
+## Decision
+
+We have established the following guidelines for Jest and Playwright testing in LWCs:
+
+### Jest Unit Tests
+
+Jest will focus on isolated component behavior, covering specific scenarios without involving the browser environment or real user workflows.
+
+Key points for Jest unit tests:
+
+- **Isolated Component Behavior**: Tests should verify the component's behavior in isolation, without dependency on external systems or other components.
+- **Mock External Dependencies**: Use mocks to simulate external dependencies, such as capabilities used from the Headless library, ensuring unit tests are fast and isolated.
+- **HTML Rendering**: Validate that the component renders the correct HTML based on its state (including but not limited to: internal state, mocked headless state) and input properties.
+- **Property Updates**: Ensure component properties update as expected in response to user interactions and lifecycle events.
+- **Edge Cases**: Cover edge cases to ensure the component handles unexpected or extreme inputs gracefully.
+
+**Example Jest Test Scenarios**:
+
+- Mock a Headless controller call to test a specific component in isolation.
+- Mock a Headless state and ensure the component renders correctly by reflecting the state in the UI.
+- Verify that clicking a button updates a specific property, that the rendered HTML reflects this change and the corresponding Headless component controller was called correctly and with the correct parameters.
+- Test a lifecycle event, such as `connectedCallback`, to confirm it initializes the component correctly.
+
+### Playwright E2E Tests
+
+Playwright E2E tests will simulate actual user actions to validate the functionality of LWCs within the full user interface and ensure interaction with external systems.
+
+Key points for Playwright E2E tests:
+
+- **User Workflow Testing**: Focus on the essential paths users take to accomplish their goals with a given component, this for all the different Quantic use cases: Search, Insight, Case assist and Recomendations.
+- **Simulate User Actions**: Test realistic user actions, such as clicking buttons, entering data, and navigating through the UI.
+- **External System Interactions**: Verify interactions with external systems, like Coveo APIs and analytics, to ensure components behave as expected in a real-world environment. This also acts as a double test because it will also notify us by failing the test if the external API contract is broken too because we test for the expected request body but also the expected response as much as possible.
+
+**Example Playwright Test Scenarios**:
+
+- A user uses a Quantic component by interacting with its multiple buttons and triggering Coveo analytics. We test that the expected analytics are sent, that the events are valid, and the response from the analytics API are correct.
+- A user navigates through a whole search workflow, interacting with multiple components. We test the expected Search API calls and responses, the analytics calls and response, and also the reactivity of the full search experience.
+- Verify the integration between the Quantic components and Salesforce. We test that modifying data through the Salesforce components has an impact and triggers the correct components reactions in a Quantic experience.
+
+## Alternatives Considered
+
+1. **Relying Solely on E2E with Cypress for All Testing**:
+   - This was used before and is now rejected because using only E2E tests would slow down feedback cycles and increase test maintenance due to the complexity of mocking and setting up end-to-end environments for every component interaction.
+
+## Consequences
+
+- This approach balances efficient, reliable test coverage with manageable test maintenance. Jest allows us to cover specific logic and UI rendering in a lightweight manner, while Playwright provides confidence that the application works as expected for end-users.
+- By clearly separating Jest and Playwright responsibilities, we prevent redundancy and maintain test suite performance.
+- We are also taking the approach of relying more on the tests already done upstream in Headless for example where each component controller is already tested too, we choose not to re-test that once you trigger a Headless action correctly, we trust that it will have the correct result on the state so we don't need to re-test all of that with e2e tests.

packages/quantic/decisions/0001-testing-strategy.md

@@ -0,0 +1,3 @@
+# Architecture Decision Records
+
+This folder contains records of key architecture and technical decisions.

packages/quantic/decisions/index.md

@@ -20,6 +20,13 @@
       "rules": {
         "@lwc/lwc/no-async-operation": "off"
       }
+    },
+    {
+      "files": ["**/e2e/*.ts"],
+      "parser": "@typescript-eslint/parser",
+      "rules": {
+        "no-redeclare": ["error", {"builtinGlobals": false}]
+      }
     }
   ]
 }

packages/quantic/force-app/main/default/.eslintrc.json

@@ -95,6 +95,7 @@
     "../../../../typings/lwc/**/*.d.ts",
     "../../../../coveo.d.ts"
   ],
+  "exclude": ["**/e2e/**"],
   "typeAcquisition": {
     "include": ["jest"]
   },

packages/quantic/force-app/main/default/lwc/jsconfig.json

@@ -0,0 +1,63 @@
+import {PagerObject} from './pagerObject';
+import {quanticBase} from '../../../../../../playwright/fixtures/baseFixture';
+import {SearchObject} from '../../../../../../playwright/page-object/searchObject';
+import {
+  searchRequestRegex,
+  insightSearchRequestRegex,
+} from '../../../../../../playwright/utils/requests';
+import {InsightSetupObject} from '../../../../../../playwright/page-object/insightSetupObject';
+import {useCaseEnum} from '../../../../../../playwright/utils/useCase';
+
+const pagerUrl = 's/quantic-pager';
+
+interface PagerOptions {
+  numberOfPages: number;
+}
+type QuanticPagerE2EFixtures = {
+  pager: PagerObject;
+  search: SearchObject;
+  options: Partial<PagerOptions>;
+};
+
+type QuanticPagerE2ESearchFixtures = QuanticPagerE2EFixtures & {
+  urlHash: string;
+};
+
+type QuanticPagerE2EInsightFixtures = QuanticPagerE2ESearchFixtures & {
+  insightSetup: InsightSetupObject;
+};
+
+export const testSearch = quanticBase.extend<QuanticPagerE2ESearchFixtures>({
+  options: {},
+  urlHash: '',
+  search: async ({page}, use) => {
+    await use(new SearchObject(page, searchRequestRegex));
+  },
+  pager: async ({page, options, configuration, search, urlHash}, use) => {
+    await page.goto(urlHash ? `${pagerUrl}#${urlHash}` : pagerUrl);
+    configuration.configure(options);
+    await search.waitForSearchResponse();
+
+    await use(new PagerObject(page));
+  },
+});
+
+export const testInsight = quanticBase.extend<QuanticPagerE2EInsightFixtures>({
+  options: {},
+  search: async ({page}, use) => {
+    await use(new SearchObject(page, insightSearchRequestRegex));
+  },
+  insightSetup: async ({page}, use) => {
+    await use(new InsightSetupObject(page));
+  },
+  pager: async ({page, options, search, configuration, insightSetup}, use) => {
+    await page.goto(pagerUrl);
+    configuration.configure({...options, useCase: useCaseEnum.insight});
+    await insightSetup.waitForInsightInterfaceInitialization();
+    await search.performSearch();
+    await search.waitForSearchResponse();
+    await use(new PagerObject(page));
+  },
+});
+
+export {expect} from '@playwright/test';

packages/quantic/force-app/main/default/lwc/quanticPager/e2e/fixture.ts

@@ -0,0 +1,69 @@
+import {Locator, Page, Request} from '@playwright/test';
+import {isUaCustomEvent} from '../../../../../../playwright/utils/requests';
+
+export class PagerObject {
+  constructor(public page: Page) {
+    this.page = page;
+  }
+
+  get nextPageButton(): Locator {
+    return this.page.getByRole('button', {name: /Next Page/i});
+  }
+
+  get previousPageButton(): Locator {
+    return this.page.getByRole('button', {name: /Previous Page/i});
+  }
+
+  get pageButtons(): Locator {
+    return this.page.locator('c-quantic-number-button button');
+  }
+
+  pageButton(pageNumber: number): Locator {
+    return this.pageButtons.nth(pageNumber - 1);
+  }
+
+  async goToLastPage(): Promise<void> {
+    await this.pageButtons.nth(-1).click();
+  }
+
+  async clickNextPageButton(): Promise<void> {
+    await this.nextPageButton.click();
+  }
+
+  async clickPreviousPageButton(): Promise<void> {
+    await this.previousPageButton.click();
+  }
+
+  async clickPageNumberButton(pageNumber: number): Promise<void> {
+    await this.pageButtons.nth(pageNumber - 1).click();
+  }
+
+  async waitForPagerUaAnalytics(eventValue): Promise<Request> {
+    const uaRequest = this.page.waitForRequest((request) => {
+      if (isUaCustomEvent(request)) {
+        const requestBody = request.postDataJSON?.();
+        const expectedFields = {
+          eventType: 'getMoreResults',
+          eventValue: eventValue,
+        };
+        return Object.keys(expectedFields).every(
+          (key) => requestBody?.[key] === expectedFields[key]
+        );
+      }
+      return false;
+    });
+    return uaRequest;
+  }
+
+  async waitForPagerNextUaAnalytics(): Promise<Request> {
+    return this.waitForPagerUaAnalytics('pagerNext');
+  }
+
+  async waitForPagerPreviousUaAnalytics(): Promise<Request> {
+    return this.waitForPagerUaAnalytics('pagerPrevious');
+  }
+
+  async waitForPagerNumberUaAnalytics(): Promise<Request> {
+    return this.waitForPagerUaAnalytics('pagerNumber');
+  }
+}