# Automation Locator Guide

This project now standardizes all Selenium/WebDriver hooks so that test
selectors stay stable even as the UI evolves.

## Naming Rules

- Use `data-testid` for every automation hook with the format
  `scope__element_name`.
- Scopes are lowercase snake case (e.g. `student_login`,
  `domain_assessment`). Element names are also snake case.
- For dynamic collections, append identifiers after the element block:
  - `domain_card__14_action`
  - `domain_question__467_option_a`
- Inputs that need native `By.id` selectors mirror the same string in
  their `id` attribute (e.g. `id="profile_editor__first_name_input"`).
- Never reuse the same `data-testid` value for two different DOM nodes.

## Scope Reference

| Scope | Description |
| --- | --- |
| `student_login` | Sign-in form at `/` |
| `mandatory_reset` | First-login password reset modal |
| `profile_incomplete` | Modal that forces profile completion |
| `profile_editor` | `/student/profile-builder` editor |
| `student_nav` | Logged-in student header/nav |
| `assessment_card` | Product cards on `/assessments` |
| `domains_page` | Domain listing screen |
| `domain_card` | Individual domain tiles |
| `domains_final_feedback` | Final feedback modal after all domains |
| `domain_assessment` | In-progress domain test experience |
| `domain_question` | Question renderer + inputs |
| `domain_feedback` | Per-domain feedback modal |

## Dynamic Element Patterns

- **Assessment cards**: `data-testid="assessment_card__{assignmentId}_action"`
- **Domain cards**: `data-testid="domain_card__{domainId}_action"`
- **Questions**:
  - Shell: `domain_question__{questionId}`
  - Options: `domain_question__{questionId}__option_{label}`
  - True/False: `domain_question__{questionId}__truefalse_{value}`
  - Rating scales: `…__rating_{score}`
  - Matrix cells: `…__matrix_{rowIndex}_{columnIndex}`

Following this table ensures every automated flow—from login through final
feedback—can rely on deterministic selectors with no brittle CSS/XPath.

