feat(cc-widgets): UI Automation for State Change

playwright.config.ts

@@ -10,7 +10,8 @@ dotenv.config({path: path.resolve(__dirname, '.env')});
  */
 export default defineConfig({
   testDir: './playwright',
-
+  /* Maximum time one test can run for. */
+  timeout: 180000,
   /* Run your local dev server before starting the tests */
   webServer: {
     command: 'yarn workspace samples-cc-react-app serve',

playwright/Utils/initUtils.ts

@@ -0,0 +1,183 @@
+import {Page, expect, BrowserContext} from '@playwright/test';
+import dotenv from 'dotenv';
+import {BASE_URL} from '../constants';
+
+dotenv.config();
+
+/**
+ * Performs login using an access token from environment variables
+ * @param page - The Playwright page object
+ * @param agentId - Agent identifier to get access token for (e.g., 'AGENT1', 'AGENT2')
+ * @description Requires PW_{agentId}_ACCESS_TOKEN environment variable to be set
+ * @throws {Error} When PW_{agentId}_ACCESS_TOKEN environment variable is not defined
+ * @example
+ * ```typescript
+ * // Ensure PW_AGENT1_ACCESS_TOKEN is set in .env file
+ * await loginViaAccessToken(page, 'AGENT1');
+ *
+ * // Different agents with their own access tokens
+ * await loginViaAccessToken(page, 'AGENT2'); // Uses PW_AGENT2_ACCESS_TOKEN
+ * await loginViaAccessToken(page, 'ADMIN');  // Uses PW_ADMIN_ACCESS_TOKEN
+ * ```
+ */
+export const loginViaAccessToken = async (page: Page, agentId: string): Promise<void> => {
+  await page.goto(BASE_URL);
+  const accessToken = process.env[`PW_${agentId}_ACCESS_TOKEN`];
+  await page.getByRole('textbox').click();
+  if (!accessToken) {
+    throw new Error(`PW_${agentId}_ACCESS_TOKEN is not defined, OAuth failed`);
+  }
+  await page.getByRole('textbox').fill(accessToken);
+};
+
+/**
+ * Performs OAuth login with Webex using agent credentials from environment variables
+ * @param page - The Playwright page object
+ * @param agentId - Agent identifier to validate against environment variables (e.g., 'AGENT1', 'AGENT2')
+ * @description Validates credentials against PW_{agentId}_USERNAME and PW_{agentId}_PASSWORD
+ * @throws {Error} When agent credentials are not found in environment variables
+ * @example
+ * ```typescript
+ * // OAuth login with agent credentials from environment variables
+ * await oauthLogin(page, 'AGENT1'); // validates against PW_AGENT1_USERNAME/PW_AGENT1_PASSWORD
+ * await oauthLogin(page, 'AGENT2'); // validates against PW_AGENT2_USERNAME/PW_AGENT2_PASSWORD
+ * await oauthLogin(page, 'ADMIN'); // validates against PW_ADMIN_USERNAME/PW_ADMIN_PASSWORD
+ * ```
+ */
+export const oauthLogin = async (page: Page, agentId: string): Promise<void> => {
+  // Check 1: Validate agentId parameter is provided
+  if (!agentId) {
+    throw new Error('Agent ID parameter is required');
+  }
+
+  // Check 2: Validate agentId is not empty string
+  if (agentId.trim() === '') {
+    throw new Error('Agent ID cannot be empty string');
+  }
+
+  // Check 3: Get credentials from environment variables
+  const username = process.env[`PW_${agentId}_USERNAME`];
+  const password = process.env[`PW_PASSWORD`];
+  // Check 4: Validate environment variables are set
+  if (!username || !password) {
+    throw new Error(`Environment variables PW_${agentId}_USERNAME and PW_PASSWORD must be set`);
+  }
+
+  await page.goto(BASE_URL);
+  await page.locator('#select-base-triggerid').getByText('Access Token').click();
+  await page.getByTestId('samples:login_option_oauth').getByText('Login with Webex').click();
+  await page.getByTestId('samples:login_with_webex_button').click();
+  await page.getByRole('textbox', {name: 'name@example.com'}).fill(username);
+  await page.getByRole('link', {name: 'Sign in'}).click();
+  await page.getByRole('textbox', {name: 'Password'}).fill(password);
+  await page.getByRole('button', {name: 'Sign in'}).click();
+};
+
+/**
+ * Enables all available contact center widgets
+ * @param page - The Playwright page object
+ * @description Checks all widget checkboxes including station login, user state, tasks, and call controls
+ * @example
+ * ```typescript
+ * await enableAllWidgets(page);
+ * await initialiseWidgets(page); // Now all widgets will be available
+ * ```
+ */
+export const enableAllWidgets = async (page: Page): Promise<void> => {
+  await page.getByTestId('samples:widget-stationLogin').check();
+  await page.getByTestId('samples:widget-userState').check();
+  await page.getByTestId('samples:widget-incomingTask').check();
+  await page.getByTestId('samples:widget-taskList').check();
+  await page.getByTestId('samples:widget-callControl').check();
+  await page.getByTestId('samples:widget-callControlCAD').check();
+  await page.getByTestId('samples:widget-outdialCall').check();
+};
+
+/**
+ * Enables multi-login functionality for the SDK
+ * @param page - The Playwright page object
+ * @description Must be called before SDK initialization to take effect
+ * @example
+ * ```typescript
+ * await enableMultiLogin(page);
+ * await initialiseWidgets(page); // Multi-login is now enabled
+ * ```
+ */
+export const enableMultiLogin = async (page: Page): Promise<void> => {
+  await page.getByTestId('samples:multi-login-enable-checkbox').check();
+};
+
+/**
+ * Disables multi-login functionality for the SDK
+ * @param page - The Playwright page object
+ * @description Must be called before SDK initialization to take effect
+ * @example
+ * ```typescript
+ * await disableMultiLogin(page);
+ * await initialiseWidgets(page); // Multi-login is now disabled
+ * ```
+ */
+export const disableMultiLogin = async (page: Page): Promise<void> => {
+  await page.getByTestId('samples:multi-login-enable-checkbox').uncheck();
+};
+
+/**
+ * Initializes the widgets by clicking the init widgets button and waiting for station-login widget to be visible
+ * @param page - The Playwright page object
+ * @description The station-login widget should be checked/enabled before using this function
+ * @throws {Error} When station-login widget is not visible after initialization
+ * @example
+ * ```typescript
+ * // Ensure station-login widget is checked first
+ * await page.getByTestId('samples:widget-stationLogin').check();
+ * await initialiseWidgets(page);
+ * ```
+ */
+export const initialiseWidgets = async (page: Page): Promise<void> => {
+  await page.getByTestId('samples:init-widgets-button').click();
+
+  await page.getByTestId('station-login-widget').waitFor({state: 'visible', timeout: 50000});
+};
+
+/**
+ * Reloads the page and reinitializes widgets to simulate agent relogin
+ * @param page - The Playwright page object
+ * @description Useful for testing state persistence after page reload
+ * @throws {Error} When widget reinitialization fails after reload
+ * @example
+ * ```typescript
+ * // Test state persistence
+ * await changeUserState(page, 'Available');
+ * await agentRelogin(page); // State should persist after reload
+ * ```
+ */
+// Helper method for agent relogin - simulates user login along with page reload
+export const agentRelogin = async (page: Page): Promise<void> => {
+  await page.reload();
+  await initialiseWidgets(page);
+};
+
+/**
+ * Creates a new page in the same browser context for multi-login testing
+ * @param context - The Playwright browser context
+ * @returns Promise<Page> - The new page with widgets initialized
+ * @description Useful for testing multi-login scenarios
+ * @throws {Error} When widget initialization fails on the new page
+ * @example
+ * ```typescript
+ * const context = await browser.newContext();
+ * const primaryPage = await context.newPage();
+ * const secondaryPage = await setupMultiLoginPage(context);
+ *
+ * // Test state synchronization between pages
+ * await changeUserState(primaryPage, 'Available');
+ * await verifyCurrentState(secondaryPage, 'Available');
+ * ```
+ */
+// Helper method for multisession - creates new page and initializes widgets in same context
+export const setupMultiLoginPage = async (context: BrowserContext): Promise<Page> => {
+  const multiLoginPage = await context.newPage();
+  await multiLoginPage.goto(BASE_URL);
+  await initialiseWidgets(multiLoginPage);
+  return multiLoginPage;
+};

playwright/Utils/stationLoginUtils.ts

@@ -0,0 +1,156 @@
+import {Page, expect} from '@playwright/test';
+import dotenv from 'dotenv';
+import {LOGIN_MODE} from '../constants';
+
+dotenv.config();
+
+/**
+ * Performs desktop login for contact center agents
+ * @param page - The Playwright page object
+ * @throws {Error} When login fails or required elements are not found
+ * @example
+ * ```typescript
+ * await desktopLogin(page);
+ * ```
+ */
+export const desktopLogin = async (page: Page): Promise<void> => {
+  await page.getByTestId('login-option-select').locator('#select-base-triggerid svg').click();
+  await page.getByTestId('login-option-Desktop').click();
+  await page.getByTestId('teams-select-dropdown').locator('#select-base-triggerid div').click();
+  await page.waitForTimeout(200);
+  await page.locator('[data-testid^="teams-dropdown-"]').nth(0).locator('span, div').first().click();
+  await page.waitForTimeout(200);
+
+  await page.getByTestId('login-button').click();
+};
+
+/**
+ * Performs extension-based login for contact center agents
+ * @param page - The Playwright page object
+ * @param extensionNumber - Optional extension number. Falls back to PW_EXTENSION_NUMBER env variable
+ * @throws {Error} When extension number is not provided or empty
+ * @throws {Error} When login fails or required elements are not found
+ * @example
+ * ```typescript
+ * // Using environment variable
+ * await extensionLogin(page);
+ *
+ * // Using custom extension number
+ * await extensionLogin(page, "1234");
+ * ```
+ */
+export const extensionLogin = async (page: Page, extensionNumber?: string): Promise<void> => {
+  const number = extensionNumber ?? process.env.PW_AGENT1_EXTENSION_NUMBER;
+  if (!number) {
+    throw new Error('PW_AGENT1_EXTENSION_NUMBER must be provided');
+  }
+
+  if (number.trim() === '') {
+    throw new Error('Extension number is empty. Please provide a valid extension number.');
+  }
+
+  await page.getByTestId('login-option-select').locator('#select-base-triggerid svg').click();
+  await page.getByTestId('login-option-Extension').click();
+  await page.getByTestId('dial-number-input').locator('input').fill(number);
+  await page.getByTestId('teams-select-dropdown').locator('#select-base-triggerid div').click();
+  await page.waitForTimeout(200);
+  await page.locator('[data-testid^="teams-dropdown-"]').nth(0).locator('span, div').first().click();
+  await page.getByTestId('login-button').click();
+};
+
+/**
+ * Performs dial number-based login for contact center agents
+ * @param page - The Playwright page object
+ * @param dialNumber - Optional dial number. Falls back to PW_DIAL_NUMBER env variable
+ * @throws {Error} When dial number is not provided or empty
+ * @throws {Error} When login fails or required elements are not found
+ * @example
+ * ```typescript
+ * // Using environment variable
+ * await dialLogin(page);
+ *
+ * // Using custom dial number
+ * await dialLogin(page, "+1234567890");
+ * ```
+ */
+export const dialLogin = async (page: Page, dialNumber?: string): Promise<void> => {
+  const number = dialNumber ?? process.env.PW_DIAL_NUMBER;
+  if (!number) {
+    throw new Error('PW_DIAL_NUMBER is not defined in the .env file');
+  }
+
+  if (number.trim() === '') {
+    throw new Error('Dial number is empty. Please provide a valid dial number.');
+  }
+
+  await page.getByTestId('login-option-select').locator('#select-base-triggerid svg').click();
+  await page.getByTestId('login-option-Dial Number').click();
+  await page.getByTestId('dial-number-input').locator('div').nth(1).click();
+  await page.getByTestId('dial-number-input').locator('input').fill(number);
+  await page.getByTestId('teams-select-dropdown').locator('#select-base-triggerid div').click();
+  await page.waitForTimeout(200);
+  await page.locator('[data-testid^="teams-dropdown-"]').nth(0).locator('span, div').first().click();
+  await page.getByTestId('login-button').click();
+};
+
+/**
+ * Performs station logout for contact center agents
+ * @param page - The Playwright page object
+ * @throws {Error} When logout fails or button remains visible after logout
+ * @example
+ * ```typescript
+ * await stationLogout(page);
+ * ```
+ */
+export const stationLogout = async (page: Page): Promise<void> => {
+  // Ensure the logout button is visible before clicking
+  const logoutButton = page.getByTestId('samples:station-logout-button');
+  const isLogoutButtonVisible = await logoutButton.isVisible().catch(() => false);
+  if (!isLogoutButtonVisible) {
+    throw new Error('Station logout button is not visible. Cannot perform logout.');
+  }
+  await page.getByTestId('samples:station-logout-button').click();
+  //check if the station logout button is hidden after logouts
+  const isLogoutButtonHidden = await page
+    .getByTestId('samples:station-logout-button')
+    .waitFor({state: 'hidden'})
+    .then(() => true)
+    .catch(() => false);
+  if (!isLogoutButtonHidden) {
+    throw new Error('Station logout button is still visible after logout');
+  }
+};
+
+/**
+ * Unified telephony login function that supports multiple login modes
+ * @param page - The Playwright page object
+ * @param mode - The login mode (Desktop, Extension, or Dial Number)
+ * @param number - Optional number for Extension or Dial Number modes
+ * @throws {Error} When unsupported login mode is provided
+ * @throws {Error} When number is required but not provided
+ * @example
+ * ```typescript
+ * // Desktop login
+ * await telephonyLogin(page, LOGIN_MODE.DESKTOP);
+ *
+ * // Extension login with env variable
+ * await telephonyLogin(page, LOGIN_MODE.EXTENSION);
+ *
+ * // Extension login with custom number
+ * await telephonyLogin(page, LOGIN_MODE.EXTENSION, "1234");
+ *
+ * // Dial number login with custom number
+ * await telephonyLogin(page, LOGIN_MODE.DIAL_NUMBER, "+1234567890");
+ * ```
+ */
+export const telephonyLogin = async (page: Page, mode: string, number?: string): Promise<void> => {
+  if (mode === LOGIN_MODE.DESKTOP) {
+    await desktopLogin(page);
+  } else if (mode === LOGIN_MODE.EXTENSION) {
+    await extensionLogin(page, number);
+  } else if (mode === LOGIN_MODE.DIAL_NUMBER) {
+    await dialLogin(page, number);
+  } else {
+    throw new Error(`Unsupported login mode: ${mode}. Use one of: ${Object.values(LOGIN_MODE).join(', ')}`);
+  }
+};