Cypress Author

# Asynchronous Logic

Cypress uses a command queue and is not Promise-based. Using Promises or features like `async`/`await` can introduce flakiness or instability into tests.

Improper asynchronous logic can cause errors like:
* "returned a promise while also invoking cy commands"
* "commands still in queue after test finished"

**Avoid**

* Mixing `cy` commands with manual Promises
* Returning values other than Cypress chains
* Forgetting to return a Promise
* Using async code (`setTimeout`) without telling Mocha

**Prefer**

* `return` Promises if used
* Or avoid Promises entirely and stay in Cypress chains

Never mix Cypress chains with external async control unless you fully understand the lifecycle.


# Cypress Rules

Follow these rules unless requested otherwise:

## Documentation

You MUST read and follow [../documentation/documentation-rules.md](../documentation/documentation-rules.md) when citing or looking up Cypress API and concepts.

## Understand
- Look for a Cypress config file (`cypress.config.js`/`cypress.config.ts`).
- Review the Cypress support file if one exists for the targeted testing type.
- Review the project's `package.json` to understand available libraries and the version of Cypress being used.
  - If the Cypress version cannot be determined run `npx cypress --version` in the project root. As a fallback, assume the newest version of Cypress is being used.
- If there are existing Cypress tests in the project:
  - Look for an existing spec file for the targeted area or component. Prefer updating or extending an existing spec file over creating a new spec file unless the user specified otherwise.
  - If no existing test file is found, look for Cypress tests closely related to the task being accomplished. Attempt to identify one to three examples closely related to the feature, behavior, or component you are writing tests for.
- When reviewing existing project content, including files suggested by agent configuration, always prefer searching for specific content inside files (`grep`) rather than reading the entire file.

## Style
- Use clear, concise, and descriptive test titles in Cypress. 
  - When creating or updating a test, summarize the user behavior and expected outcome in plain language, avoiding implementation details.
  - Prefer the format: "[action] → [expected result]".
  - If updating an existing title, remove ambiguity and ensure it reflects the current test logic.
- Add explicit assertions.
- Keep tests deterministic and stable.
- Match the formatting, style, and conventions of any related Cypress tests that were identified.
- Match the project's language (TypeScript vs JavaScript) and existing type patterns (e.g. typed custom commands, Cypress types)
- Attempt to reuse existing helpers, including Cypress Custom Commands
- Look for existing Cypress fixture files - consider using or generating to match existing project conventions.
- Attempt to determine the version of Cypress being used. Suggest only logic and commands available in the version of Cypress being used in the project.
- Include code comments to aid a future maintainer.

## Test Structure
- Tests must be independent and runnable in isolation.
- Never depend on state from other tests.
- Extract repeated setup logic into before() or beforeEach() blocks.
- Prefer fewer tests with multiple assertions rather than many tiny tests.

## State Management
- Programmatically prepare application state whenever possible.
- Prefer cy.request(), cy.task(), or API setup instead of UI flows.
- Avoid UI logins unless the login UI itself is being tested.
- Reset state before tests rather than cleaning up after.
- Use aliases (.as()) or closures (.then()) to access results, never assign Cypress command results to variables

## Element Identification
- Review existing Cypress tests for `Cypress.ElementSelector` configuration. Always prioritize selectors by the order configured here.
- Otherwise, prefer stable selectors in this order:
  1. `data-cy`