ISA-Frontend/.claude/commands/dev-add-e2e-attrs.md

/dev:add-e2e-attrs - Add E2E Test Attributes

Add required E2E test attributes (data-what, data-which, dynamic data-*) to component templates for QA automation.

Parameters

• component-path: Path to component directory or HTML template file

Required E2E Attributes

Core Attributes (Required)

1. data-what: Semantic description of element's purpose
   • Example: data-what="submit-button", data-what="search-input"
2. data-which: Unique identifier for the specific instance
   • Example: data-which="primary", data-which="customer-{{ customerId }}"

Dynamic Attributes (Contextual)

3. data-*: Additional context based on state/data
   • Example: data-status="active", data-index="0"

Tasks

1. Analyze Component Template

• Read component HTML template
• Identify interactive elements that need E2E attributes:
  • Buttons (button, ui-button)
  • Inputs (input, textarea, select)
  • Links (a, routerLink)
  • Custom interactive components
  • Form elements
  • Clickable elements ((click) handlers)

2. Add Missing Attributes

Buttons:

<!-- BEFORE -->
<button (click)="submit()">Submit</button>

<!-- AFTER -->
<button
  (click)="submit()"
  data-what="submit-button"
  data-which="form-primary">
  Submit
</button>

Inputs:

<!-- BEFORE -->
<input [(ngModel)]="searchTerm" placeholder="Search..." />

<!-- AFTER -->
<input
  [(ngModel)]="searchTerm"
  placeholder="Search..."
  data-what="search-input"
  data-which="main-search" />

Dynamic Lists:

<!-- BEFORE -->
@for (item of items; track item.id) {
  <li (click)="selectItem(item)">{{ item.name }}</li>
}

<!-- AFTER -->
@for (item of items; track item.id) {
  <li
    (click)="selectItem(item)"
    data-what="list-item"
    [attr.data-which]="item.id"
    [attr.data-status]="item.status">
    {{ item.name }}
  </li>
}

Links:

<!-- BEFORE -->
<a routerLink="/orders/{{ orderId }}">View Order</a>

<!-- AFTER -->
<a
  [routerLink]="['/orders', orderId]"
  data-what="order-link"
  [attr.data-which]="orderId">
  View Order
</a>

Custom Components:

<!-- BEFORE -->
<ui-button (click)="save()">Save</ui-button>

<!-- AFTER -->
<ui-button
  (click)="save()"
  data-what="save-button"
  data-which="order-form">
  Save
</ui-button>

3. Naming Conventions

data-what Guidelines:

• Use kebab-case
• Be descriptive but concise
• Common patterns:
  • *-button (submit-button, cancel-button, delete-button)
  • *-input (email-input, search-input, quantity-input)
  • *-link (product-link, order-link, customer-link)
  • *-item (list-item, menu-item, card-item)
  • *-dialog (confirm-dialog, error-dialog)
  • *-dropdown (status-dropdown, category-dropdown)

data-which Guidelines:

• Unique identifier for the instance
• Use dynamic binding for list items: [attr.data-which]="item.id"
• Static for unique elements: data-which="primary"
• Combine with context: data-which="customer-{{ customerId }}-edit"

4. Scan for Coverage

Check template coverage:

# Count interactive elements
grep -E '(click)=|routerLink|button|input|select|textarea' [template-file]

# Count elements with data-what
grep -c 'data-what=' [template-file]

# List elements missing E2E attributes
grep -E '(click)=|button' [template-file] | grep -v 'data-what='

5. Validate Attributes

• No duplicates in data-which within same view
• All interactive elements have both data-what and data-which
• Dynamic attributes use proper Angular binding: [attr.data-*]
• Attributes don't contain sensitive data (passwords, tokens)

6. Update Component Tests

Add E2E attribute selectors to tests:

// Use E2E attributes for element selection
const submitButton = fixture.nativeElement.querySelector('[data-what="submit-button"][data-which="primary"]');
expect(submitButton).toBeTruthy();

7. Document Attributes

Add comment block at top of template:

<!--
E2E Test Attributes:
- data-what="submit-button" data-which="primary" - Main form submission
- data-what="cancel-button" data-which="primary" - Cancel action
- data-what="search-input" data-which="main" - Product search field
-->

Output

Provide summary:

• Template analyzed: [path]
• Interactive elements found: [count]
• Attributes added: [count]
• Coverage: [percentage]% (elements with E2E attrs / total interactive elements)
• List of added attributes with descriptions
• Validation status: ✅/❌

Common Patterns by Component Type

Form Components:

• data-what="[field]-input" data-which="[form-name]"
• data-what="submit-button" data-which="[form-name]"
• data-what="cancel-button" data-which="[form-name]"

List/Table Components:

• data-what="list-item" [attr.data-which]="item.id"
• data-what="edit-button" [attr.data-which]="item.id"
• data-what="delete-button" [attr.data-which]="item.id"

Navigation Components:

• data-what="nav-link" data-which="[destination]"
• data-what="breadcrumb" data-which="[level]"

Dialog Components:

• data-what="confirm-button" data-which="dialog"
• data-what="close-button" data-which="dialog"

References

• CLAUDE.md Code Quality section (E2E Testing Requirements)
• docs/guidelines/testing.md
• QA team E2E test documentation (if available)