El localizador es un contrato, no una coordenada
CSS y XPath suelen describir dónde está un botón, no para qué sirve. Los roles, las etiquetas y los identificadores de prueba dan a Playwright un contrato más estable.
Edición traducida. Los identificadores técnicos permanecen en su forma original.
page.locator('.panel > div:nth-child(3) > button.primary') funciona hoy. Funciona mañana. Sigue funcionando hasta que un diseñador mueve el botón una ranura hacia la izquierda y luego su suite falla en una característica que nadie rompió. No escribiste una prueba. Escribiste una fotografía del DOM.
Lo que realmente recomienda Playwright
La documentación de Playwright es inusualmente directa al respecto. Su guía de localizadores recomienda priorizar los atributos de cara al usuario y los contratos explícitos: getByRole, getByLabel, getByText, getByPlaceholder, getByTestId. Los localizadores de roles reflejan cómo los usuarios y la tecnología de asistencia perciben la página. Los identificadores de prueba crean un contrato explícito separado, al precio de ser invisibles para los usuarios. Permanecen estables sólo si los desarrolladores preservan ese contrato. Los selectores CSS y XPath están documentados como frágiles porque están vinculados a la estructura DOM, y la estructura DOM es lo que cambia.
Dos propiedades del marco premian el buen hábito. Los localizadores se vuelven a resolver antes de cada acción, por lo que una nueva renderización entre dos pasos no lo deja con un elemento obsoleto. Y los localizadores son estrictos: si su selector coincide con dos elementos, la acción arroja en lugar de hacer clic silenciosamente en el primero. Una falla estricta en CI resulta molesta por una tarde. Un clic incorrecto en el cuadro de diálogo incorrecto es un informe de error con su nombre.
¿Por qué los generadores adoptan primero el mal hábito?
Una suite generada puede buscar un selector que se resuelva en la página actual sin considerar qué cambiará un rediseño. Se trata de un riesgo de revisión, no de evidencia sobre los datos de entrenamiento de ningún modelo en particular. Las pruebas vinculadas al diseño pueden aprobarse el primer día y fallar después de un cambio de interfaz por motivos no relacionados con el comportamiento del producto.
El fracaso es costoso de una manera específica: la suite llora en cada rediseño, el equipo aprende a ignorar las versiones rojas y la única regresión real atraviesa una pared de ruido familiar.
Una auditoría de quince minutos para cualquier suite
Prepare sus pruebas para page.locator con cadenas CSS o XPath, y para getByText utilizado en elementos interactivos. Para cada visita, haga una pregunta: ¿este selector nombra cuál es el elemento o dónde se ubica? Reemplazar coordenadas con contratos:
- Botones y enlaces:
getByRolecon el nombre accesible. - Campos de formulario:
getByLabelogetByPlaceholdercomo alternativa. - Contenido repetido o dinámico: un
data-testidacordado con los desarrolladores. getByText: útil para contenido de texto; prefiera una función y un nombre accesible al hacer clic en un control.
Te quedarás con un puñado de controles genuinamente ambiguos. Esos no son un problema de prueba. Son un problema de accesibilidad que las pruebas acaban de encontrar de forma gratuita.
La trampa del rigor, y cuando first() es una confesión
Los localizadores de dramaturgos son estrictos: una acción en un selector que coincide con dos elementos genera una infracción en lugar de adivinar. Trate cada error en modo estricto como una cuestión de diseño. Si necesita .first() para aprobar la suite, una de dos cosas es cierta: la página muestra controles duplicados que deberían tener nombres accesibles distintos, o su selector es demasiado ancho. Ambos son hallazgos, no inconvenientes. La solución es limitarse a un contrato con nombre, filtrar por padre estable o solicitar una identificación de prueba. Buscar .nth(1) porque la segunda coincidencia resulta ser la correcta esta semana es la forma en que las suites aprenden a hacer clic en el cuadro de diálogo incorrecto después del próximo lanzamiento.
Hay una vía de escape legítima. locator.or() existe para los casos en los que la página muestra honestamente uno de dos estados, como un formulario de inicio de sesión o un banner de inicio de sesión. Úselo deliberadamente, con ambas alternativas nombradas y se lee como una rama. Úselo para disimular la ambigüedad y se leerá como un encogimiento de hombros.
Dónde encajan los agentes
Deje que el agente explore y redacte; los localizadores son donde vive su reseña. Una prueba generada con getByRole('button', { name: 'Save' }) le indica lo que cree que hace la página. Una prueba generada con div:nth-child(3) no le dice nada excepto que el DOM se veía así una vez. Conserva el primer tipo. Vuelva a escribir el segundo antes de que llegue a CI, porque cada localizador frágil que acepte es una futura falsa alarma por la que ya ha pagado.
Preguntas comunes
¿Cuál es la estrategia de localización más confiable en Playwright?
Playwright recomienda atributos orientados al usuario y contratos explícitos: atributos getByRole, getByLabel, getByText y data-testid. Los selectores CSS y XPath están documentados como frágiles porque acoplan pruebas a la estructura DOM.
¿Son los atributos data-testid mejores que los localizadores de roles?
Resuelven diferentes problemas. Los identificadores de prueba sobreviven a cualquier cambio visual o estructural, pero no dicen nada sobre lo que ve el usuario. Los localizadores de roles también funcionan como una verificación de accesibilidad liviana. La mayoría de las suites para adultos utilizan roles y etiquetas primero, prueban identificadores para contenido repetido o generado.
¿Por qué las herramientas de IA generan selectores CSS con tanta frecuencia?
Un generador puede elegir un selector que funcione en la página actual sin comprobar su estabilidad durante el rediseño. El motivo depende de la herramienta; auditar su salida en lugar de asumir nada sobre los datos de entrenamiento.