## EUI Automation: Overview and Conventions

This document is the single source of truth for how this repository structures WebdriverIO/Mocha-based end-to-end automation for EUI applications. It summarizes the framework layout, how to build maintainable page objects and components, and the core rules we follow.

### Repositories and roles

- CSDR ROOT: Main repo to launch tests; holds shared scripts/config. Usually no changes needed for app-specific work.
- eui-automation (this repo): Core WDIO test framework, EUI component objects, reporting, shared actions (e.g., EU Login), services.
- Test app repo: App-specific page objects, components, tests, and config extending this framework.

### Repository structure (package)

- actions: Reusable test scenarios composed of multiple commands (e.g., login, logout).
- commands: Custom/overridden WDIO commands. Filename matches command name (e.g., click.js). These are applied from page objects as required.
- components: Object representations of UI components using XPath-only selectors. All components extend `components/component.js` and may return other components.
- core: Core utilities (reporter, services, network tools, etc.).
- pages: Page objects that compose components in the correct hierarchy. All pages extend `pages/base.js`.
- tests: Test configuration files and specs. All configs extend `wdio.conf.js` and rely on shared hooks (reporter, expect lib, etc.).

### Repository structure (test app)

- actions: App-level reusable scenarios, typically a class per page.
- commands (optional): App-specific custom WDIO commands; applied from page objects.
- components: App-specific components extending `@eui/automation/components/component.js`. Avoid translatable text in selectors.
- pages: App page objects extending `@eui/automation/pages/base.js`. Make them reusable; prefer a base page for shared UI.
- tests: Test configs and specs extending `@eui/automation/wdio.conf.js`. In specs, use page objects, actions, and translations.
- translations (optional): JSON files per page to test translations/text.
- watchscenarios: Watcher scenarios to handle asynchronous, non-blocking situations during tests.
- scripts.json: Defines npm scripts to be included in the root package.json of csdr.

### Components: principles and usage

- Components represent XPath-only selectors of UI widgets.
- All components extend `@eui/automation/components/component.js` (or an intermediate component that in turn extends it).
- Components are mutable: methods like `byIndex`, `byText`, etc., modify the component's `currentPath`. Always return new component instances from methods to avoid surprising state changes.

#### Instantiation

- The base `Component` expects a `parent` and a `selector`.
  - `parent`: another `Component` (uses its `currentPath`) or an XPath string.
  - `selector`: XPath string identifying the lowest-level element of the component (no leading `//`).
- The `currentPath` is constructed as: `parent + "//" + selector` and is modified by by-methods.

#### By-methods and indexing

- `byIndex(n)`: returns the nth instance. Wraps the XPath with `( ... )[n]`.
- `byTextContains(text)`: finds descendants whose normalized text contains `text` and returns the owning component via `ancestor-or-self`.
- `andByIndex(n)`: chain an index after a by-method to select a specific occurrence.
- `byDefault()`: reset the `currentPath` to the initial state of the component instance.

Example chaining (simplified):

1) Start with a `ux-tree-list` and get its items: `treeListItemCO`
2) Filter items by text and then pick the 3rd:
   - `treeListItemCO.byTextContains("Foo").andByIndex(3)`

This yields an XPath of the form:

`(//...//ux-tree-list//ux-tree-list-item/descendant-or-self::*[contains(normalize-space(), "Foo")]/ancestor-or-self::ux-tree-list-item[1])[3]`

#### Element access

- `element()` returns the WDIO element for the component's `currentPath`.
- Components may expose other selectors as XPath strings. Wrap with `$()` or `$$()` to obtain WDIO element(s).

### Pages

- Pages extend `BasePage` and compose components to reflect on-page hierarchy.
- Avoid translatable text in page objects; selectors must work across languages.
- Favor reusability: extract shared UI into an app base page and extend it.

### Tests

- Configs extend the master `wdio.conf.js` and share hooks for reporter and expectations.
- Specs should rely on page objects, actions, and translations where relevant.

### Vault and secrets

- Configure Vault via `config.vaultConfig` in your WDIO config (user/password or token). Ensure `endpoint` and auth are set; tests will error if missing.
- Test users: define `config.testUsers` and `config.userenv`. The framework loads secrets from `config.vaultConfig.testusersPath` (default `/secret/test_users/`) into `config.testUserData` before tests.
- Env vars from Vault: set `config.vaultEnvVars` entries with `{ path, key }`; values are injected into process env unless already set.
- Azure maintenance events: `config.azureMaintEventConfig` supports a nested `vaultConfig` to fetch its settings at startup.
- Publishers: reporters can have `vaultConfig` to fetch credentials at publish time.
- Optionally use `_CSDR_ARGS` with `@eui/tools/scripts/utils/tools.js#getArgs()` to supply `vaultUser`/`vaultPassword`.

See `wdio.conf.js` for where these are applied.

### Accessibility testing (AxeService)

- Service `services/AxeService.js`; usage docs in `services/AxeService.README.md`.
- Adds `browser.runAxe(options)`; attaches HTML/JSON to Allure; supports `failOnAccessibility` thresholds to fail tests.

### Load testing (TAF Load Orchestrator)

- `core/load-orchestrator/` contains the MQTT-based orchestrator and a WDIO `load-service.js` to coordinate workers.
- Configure WDIO services with `[LoadService, { loadTestData, instances, loadOrchestrator, storePort }]` in a load config.
- Use sync points in tests by setting `global.workerConfig.syncpoint = 'name'`; workers resume when all reach the point.
- Worker ramp-up is supported to stagger browser starts; see `core/load-orchestrator/README.md` for patterns and reporting setup.



