Configure framework to prefer data-test-id attributes for stable test selectors

LEEME.md

@@ -24,6 +24,38 @@ Podrás acceder a mi canal de [YouTube](https://www.youtube.com/c/CharlyAutomati
 
 ### Instalación del framework de pruebas
 
+#### **Mejores Prácticas: Usando atributos data-test-id**
+
+Este framework está configurado para preferir atributos `data-test-id` para localizar elementos. Esto proporciona selectores de prueba más estables y mantenibles en comparación con selectores CSS o XPath que pueden romperse cuando cambia la interfaz de usuario.
+
+**Configuración:**
+
+El archivo `playwright.config.ts` está configurado con:
+```typescript
+use: {
+  testIdAttribute: 'data-test-id',
+  // ... otras configuraciones
+}
+```
+
+**Uso en Page Objects:**
+
+Cuando la aplicación tiene atributos `data-test-id`, usa `page.getByTestId()`:
+
+```typescript
+// Enfoque recomendado
+this.username = page.getByTestId('username');
+this.password = page.getByTestId('password');
+this.signIn = page.getByTestId('sign-in-button');
+```
+
+**Beneficios:**
+- Selectores más estables que no se rompen cuando cambian las clases CSS o la estructura del DOM
+- Intención más clara - el ID de prueba marca explícitamente los elementos como objetivos de automatización de pruebas
+- Mejor separación entre las preocupaciones de estilo y pruebas
+
+Para más información, consulta la [documentación de Playwright sobre test IDs](https://playwright.dev/docs/locators#locate-by-test-id).
+
 #### **Clonar el repositorio:**
 
     git clone https://github.com/charlyautomatiza/starter-playwright.git

README.md

@@ -32,6 +32,38 @@ Download and install
 
 ### Installation of the testing framework
 
+#### **Best Practices: Using data-test-id Attributes**
+
+This framework is configured to prefer `data-test-id` attributes for locating elements. This provides more stable and maintainable test selectors compared to CSS or XPath selectors that can break when the UI changes.
+
+**Configuration:**
+
+The `playwright.config.ts` file is configured with:
+```typescript
+use: {
+  testIdAttribute: 'data-test-id',
+  // ... other settings
+}
+```
+
+**Usage in Page Objects:**
+
+When the application has `data-test-id` attributes, use `page.getByTestId()`:
+
+```typescript
+// Recommended approach
+this.username = page.getByTestId('username');
+this.password = page.getByTestId('password');
+this.signIn = page.getByTestId('sign-in-button');
+```
+
+**Benefits:**
+- More stable selectors that don't break when CSS classes or DOM structure changes
+- Clearer intent - the test ID explicitly marks elements as test automation targets
+- Better separation between styling and testing concerns
+
+For more information, see the [Playwright documentation on test IDs](https://playwright.dev/docs/locators#locate-by-test-id).
+
 #### **Clone the repository:**
 
     git clone https://github.com/charlyautomatiza/starter-playwright.git

playwright.config.ts

@@ -50,6 +50,9 @@ const config: PlaywrightTestConfig = {
 
     /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
     trace: 'on-first-retry',
+
+    /* Configure custom test ID attribute for more stable selectors. See https://playwright.dev/docs/locators#locate-by-test-id */
+    testIdAttribute: 'data-test-id',
   },
 
   /* Configure projects for major browsers */

tests/pageobjects/login.ts

@@ -8,6 +8,15 @@ export class Login {
 
   constructor(page: Page) {
     this.page = page;
+    // Best practice: Use data-test-id attributes for stable, maintainable selectors
+    // The framework is configured with testIdAttribute: 'data-test-id' in playwright.config.ts
+    // 
+    // Preferred approach (when the application has data-test-id attributes):
+    // this.username = page.getByTestId('username');
+    // this.password = page.getByTestId('password');
+    // this.signIn = page.getByTestId('sign-in-button');
+    //
+    // Current implementation uses fragile XPath selectors as fallback:
     this.username = page.locator('(//input[@id="outlined-name"])[1]');
     this.password = page.locator('(//input[@id="outlined-name"])[2]');
     this.signIn = page.locator('(//span[normalize-space()="SIGN IN"])[1]');

tests/pageobjects/tasks.ts

@@ -7,6 +7,14 @@ export class Tasks {
 
   constructor(page: Page) {
     this.page = page;
+    // Best practice: Use data-test-id attributes for stable, maintainable selectors
+    // The framework is configured with testIdAttribute: 'data-test-id' in playwright.config.ts
+    //
+    // Preferred approach (when the application has data-test-id attributes):
+    // this.search = page.getByTestId('search-input');
+    // this.taskTitle = page.getByTestId('task-title');
+    //
+    // Current implementation uses fragile CSS/XPath selectors as fallback:
     this.search = page.locator('input[placeholder="Search..."]');
     this.taskTitle = page.locator('(//div[@class="MuiCardContent-root"]/h1)[1]');
   }