# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Repository Is

`@sap_oss/wdio-qmate-service` is a WebdriverIO plugin that extends WebdriverIO with domain-specific testing modules for SAP UI5 applications, non-UI5 web apps, mobile testing, and API/service testing. It compiles to CommonJS (`./lib/`) and is consumed as a WebdriverIO service.

## Commands

```bash
# Build (required before running integration tests)
npm run build         # locator build + tsc
npm run build:dev     # watch mode (tsc --watch)

# Lint / Format
npm run lint          # ESLint
npm run lint:fix      # ESLint with auto-fix
npm run prettier      # Check formatting
npm run prettier:fix  # Auto-fix formatting

# Unit tests (Vitest — fast, no browser needed)
npm run test:unit
npm run test:unit:watch

# Integration tests (require Chrome + built lib/)
npx wdio ./test/reuse/util/data/test.data.conf.js   # example: run a single module's tests
npm run test:reuse:util          # all util module tests
npm run test:reuse:ui5           # all UI5 module tests
npm run test:reuse               # all reuse module tests

# Docs
npm run serve-docs               # generate and serve locally (requires mkdocs)
```

## Architecture

### Service Lifecycle

`src/index.ts` is the WebdriverIO service entry point. It implements WebdriverIO's service hooks (`onPrepare`, `beforeSession`, `before`, `after`, `onComplete`) and delegates to scripts under `src/scripts/hooks/`. The `before` hook is the main one — it initialises the global namespaces by calling `src/reuse/index.ts`.

### Global Namespaces

`src/reuse/index.ts` (the `ReuseLibrary` class) instantiates every module and assigns them to `global.*`. Test specs access everything through these globals — no imports required:

| Global | Source directory | Purpose |
|--------|-----------------|---------|
| `global.common` | `src/reuse/modules/common/` | Cross-platform: assertion, date, navigation, userInteraction |
| `global.util` | `src/reuse/modules/util/` | browser, console, data, file, formatter, function, system, component, userSettings |
| `global.ui5` | `src/reuse/modules/ui5/` | SAP UI5 controls: assertion, control, element, session, table, navigation, confirmationDialog, errorDialog, navigationBar, footerBar, mockserver, qunit |
| `global.nonUi5` | `src/reuse/modules/nonUi5/` | Standard web: assertion, element, navigation, userInteraction, session |
| `global.service` | `src/reuse/modules/service/` | API clients: odata, rest |
| `global.mobile` | `src/reuse/modules/mobile/` | element, userInteraction, gestures, device, android, ios |
| `global.flp` | `src/reuse/modules/flp/` | Fiori Launchpad: userSettings, userLocks |
| `global.cit` | `src/reuse/runner/` | Test runner utilities |

ESLint is configured to recognise all these as globals (see `.eslintrc.yml`), so `no-undef` won't fire on them.

### Build Pipeline

1. `src/scripts/locators/qmateLocatorSrc/build.js` — bundles the locator script (esbuild)
2. `tsc` — compiles all `src/**/*.ts` to `./lib/` (ES2024 target, CommonJS, strict)

Always run `npm run build` before running integration tests; the tests load from `./lib/`.

### Test Layout

- `test/unit/` — Vitest unit tests (minimal coverage, very fast)
- `test/reuse/<namespace>/<module>/` — Each module has its own wdio config (`test.*.conf.js`) and spec files. Run a single module in isolation with `npx wdio ./test/reuse/<namespace>/<module>/test.*.conf.js`.
- `test/core/` — Data exchange, functional chaining, locator, and watch-mode tests
- `test/authenticator/` — Authentication flow tests (staticLogin / systemLogin variants)

### Local Package

`packages/qcrypt/` is a local `file:` dependency providing the encryption/decryption primitives used by `util.data.decrypt` and the secure-data flow in `src/reuse/modules/util/data.ts`.

## Code Conventions

- **2-space indentation**, **double quotes**, **semicolons** (enforced by ESLint + Prettier)
- Prettier `printWidth` is 300 — long lines are acceptable
- Every module class is instantiated and exported as a singleton (`export default new Foo()`)
- JSDoc comments on public methods feed the doc generator (`npm run generate-docs`)
- `VerboseLoggerFactory` and `ErrorHandler` are the standard logging/error patterns — use `this.vlf.initLog(this.methodName)` at the top of every method