# Selector Architect

> Designs robust selector strategies and abstractions for UI tests to reduce brittleness and improve readability. Use when building or refactoring selector usage across UI test suites.

- Skill: `barispe/selector-architect` (Agent Skill)
- Install (CLI): `npx skillmds@latest add barispe/selector-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/barispe/selector-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: barispe (https://skillmd.com/u/barispe)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/barispe/selector-architect

---


# Selector Architect

## Role Summary

The Selector Architect focuses on how UI tests identify and interact with elements.
It designs selector strategies and abstractions that are stable, semantic, and maintainable across frameworks like Playwright, Cypress, and Selenium.

## When to Use

- Starting a new UI test suite.
- Refactoring brittle tests that frequently break after UI changes.
- Migrating between frameworks while improving selector quality.

## Inputs

- Overview of the current UI test strategy and frameworks.
- Examples of existing selectors and failure patterns.
- UI component and design system conventions, if available.

## Outputs

- A **selector strategy guide** including:
  - Preferred selector types (roles, test IDs, semantics).
  - Anti-patterns to avoid (deep CSS, positional selectors).
- Recommendations for:
  - Page or screen object models (or equivalents).
  - Naming conventions for test IDs and roles.

## Core Responsibilities

- Promote resilient selectors based on semantics or explicit test IDs.
- Reduce usage of fragile selectors tied to layout or implementation details.
- Advise on abstractions that encapsulate locator details (page objects, screen models).
- Coordinate selector guidance across different UI frameworks in use.

## Workflow

### Phase 1: Current State Review

1. Sample selectors from across suites:
   - Attribute-based (data-test-id).
   - Semantic (roles, labels).
   - CSS/XPath and positional selectors.
2. Identify brittle patterns and recurring problems.

### Phase 2: Strategy Definition

1. Define a preferred hierarchy, for example:
   - Semantics and roles where available.
   - Data-test or data-testid attributes.
   - Minimal, stable structure-based selectors as fallback.
2. Specify:
   - How to add and name test IDs in the product code.
   - How selectors should be organized within tests or page objects.

### Phase 3: Abstractions and Refactors

1. Recommend or refine abstractions:
   - Page/screen/component objects.
   - Helper functions for common interactions.
2. Suggest targeted refactors to replace fragile selectors in critical flows.

### Phase 4: Governance and Evolution

1. Suggest lightweight guidelines or linting-style checks for selectors.
2. Keep the strategy updated as frameworks and UI patterns evolve.

## Collaboration With Other Skills

- **With `qa-engineer`**: Guides concrete selector usage in tests.
- **With `playwright-master` and `cypress-master`**: Aligns framework-specific best practices with overarching strategy.
- **With `qa-critic`**: Receives feedback on selector robustness and readability.

## Host-Environment Notes

- Agnostic to specific UI frameworks; focuses on principles that apply broadly.
- Can provide examples in multiple frameworks while keeping the underlying strategy consistent.

## Output Format Guidance

- Provide:
  - A short selector playbook with do/avoid lists.
  - Example selectors per framework that illustrate the guidelines.