.cursorrules (deprecated)

1# Project: WebdriverIO Test Automation Framework
2 
3## Framework Structure
4- Use WebdriverIO (WDIO) as the primary test runner and automation framework
5- Implement Page Object Model pattern with dedicated page classes
6- Organise specs, page objects, and helpers in separate directories
7- Use TypeScript for type-safe test implementations
8- Configure wdio.conf.ts as the single source of truth for runner settings
9 
10## Coding Standards
11- Follow TypeScript and ESLint best practices
12- Use Prettier for consistent code formatting
13- Maximum line length: 100 characters
14- Use async/await for all browser interactions; never mix callbacks with async patterns
15- Name page object files with `.page.ts` suffix (e.g. `login.page.ts`)
16 
17## Test Organisation
18- Group related tests in `describe` blocks reflecting user journeys or features
19- Use `it`/`test` with descriptive names that read as requirements
20- Keep specs focused: one user story or scenario per spec file
21- Use Mocha hooks (`before`, `beforeEach`, `after`, `afterEach`) for setup and teardown
22- Separate smoke, regression, and integration suites in `wdio.conf.ts` via `suites`
23 
24## Best Practices
25- Rely on WDIO's built-in auto-waiting; avoid manual `browser.pause()` calls
26- Use `$` / `$$` selectors with `data-testid` attributes for stable element references
27- Chain assertions with `expect()` from `@wdio/globals` for readable output
28- Keep page objects free of assertions; put assertions in spec files only
29- Use `browser.url()` with relative paths; set `baseUrl` in config
30 
31## Element Handling
32- Prefer semantic selectors: `aria/`, role-based, then `data-testid`, last resort CSS
33- Cache selectors as getter properties in page objects for lazy evaluation
34- Use `waitForDisplayed`, `waitForEnabled`, and `waitForExist` with explicit timeouts
35- Handle iframes with `browser.switchToFrame()` and always switch back after interaction
36- Interact with shadow DOM via `shadow$` / `shadow$$` selectors
37 
38## Page Object Pattern
39```typescript
40// pages/login.page.ts
41import { $ } from '@wdio/globals'
42 
43class LoginPage {
44  get emailInput()    { return $('[data-testid="email-input"]') }
45  get passwordInput() { return $('[data-testid="password-input"]') }
46  get submitButton()  { return $('[data-testid="submit-button"]') }
47  get errorMessage()  { return $('[data-testid="error-message"]') }
48 
49  async open() {
50    await browser.url('/login')
51  }
52 
53  async login(email: string, password: string) {
54    await this.emailInput.setValue(email)
55    await this.passwordInput.setValue(password)
56    await this.submitButton.click()
57  }
58}
59 
60export default new LoginPage()
61```
62 
63## Test Data Management
64- Store test credentials and base URLs in environment variables via `dotenv`
65- Use fixtures for reusable datasets; never hardcode sensitive values in specs
66- Generate dynamic test data with `@faker-js/faker` for isolation between runs
67- Clean up created test data in `after`/`afterEach` hooks or via API calls
68 
69## Configuration
70- Define separate `wdio.conf.ts` files for local, CI, and cross-browser runs
71- Enable `headless` mode in CI; keep headed mode available for local debugging
72- Set `maxInstances` and `bail` values appropriate to the target environment
73- Configure `specFileRetries` sparingly (1–2 max) to handle genuine flakiness
74- Use `@wdio/allure-reporter` or `spec` reporter based on environment
75 
76## API Integration
77- Call REST endpoints directly in `before` hooks to seed or reset state
78- Use `browser.mock()` to intercept and stub network requests in component tests
79- Validate API responses alongside UI assertions for end-to-end coverage
80- Prefer API teardown over UI teardown for speed
81 
82## Visual Testing
83- Integrate `@wdio/visual-service` for screenshot comparison
84- Store baseline images under version control in a dedicated `visual-baselines/` folder
85- Update baselines intentionally with `--updateSnapshots` flag; review diffs in PRs
86- Mask dynamic regions (timestamps, ads) to reduce false positives
87 
88## Mobile Testing
89- Extend the same Page Object pattern for Appium-backed WDIO mobile configs
90- Use `driver.isAndroid` / `driver.isIOS` guards only where platform behaviour differs
91- Manage real-device or emulator caps in separate `wdio.mobile.conf.ts`
92 
93## CI/CD Integration
94- Run WDIO in parallel with `--maxInstances` tuned to available CI workers
95- Upload Allure or JUnit XML reports as CI artefacts for every pipeline run
96- Fail the pipeline on test failure; use exit code from `wdio` CLI directly
97- Cache `node_modules` and browser binaries between pipeline runs for speed
98 
99## Reporting
100- Use `@wdio/allure-reporter` for detailed HTML reports with screenshots on failure
101- Attach screenshots automatically in `afterTest` hook when the test fails
102- Capture browser logs and append to report output for debugging
103- Configure `--reporter=spec` locally for readable terminal output
104 
105## Documentation
106- Document selector strategy and page object conventions in `docs/CONTRIBUTING.md`
107- Maintain a `README.md` with setup instructions, environment variables, and run commands
108- Add JSDoc comments to page object methods describing parameters and side effects
109- Include architecture diagram showing config → spec → page object → helper relationships
110 
111Remember to leverage WebdriverIO's protocol-agnostic design: the same framework configuration supports Selenium, Chrome DevTools Protocol (CDP), and Appium with minimal changes.
112