feat: release v1.24.1 with a new CLAUDE.md template for project instructions, improved locator strategies in documentation, and enhancements to the setup script for automatic CLAUDE.md installation

Author: vasu31dev

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.24.1] - 2026-03-17
+
+### Added
+
+- **CLAUDE.md template:** New `templates/CLAUDE.md` with project overview, structure, conventions, and AI tooling for Playwright TypeScript projects. Setup script copies it to the project root when installing skills (unless one exists; use `--force` to overwrite).
+- **Setup (bin/setup.js):** When installing skills, setup now installs the CLAUDE.md template and links the Cursor project rule so Cursor and Claude Code share the same project instructions.
+
+### Changed
+
+- **Locators skill (references/locators.md):** Priority reordered so unique **XPath/CSS with stable attributes** come before **role/text** locators. Prefer stable selectors so failures distinguish "element missing" (bug) from "copy/locale changed." Added checkout-complete example using `[data-test="complete-header"]` and asserting text separately.
+- **Sauce Demo checkout page:** `orderCompleteMessage` now uses stable selector `getLocator('[data-test="complete-header"]')` instead of `getLocatorByRole('heading', { name: /thank you for your order/i })`; text is still asserted in `expectElementToContainText`.
+- **Package:** `overrides` added so `playwright` resolves to stable only (`^1.58.2`) when using `@playwright/cli`; `templates` included in published `files`.
+- **Agents:** Minor updates to playwright-test-generator, playwright-test-healer, and playwright-test-planner.
+- **Cursor rules / README:** Small updates for project and docs.
+
 ## [1.24.0] - 2026-03-16
 
 ### Added

README.md

@@ -93,10 +93,11 @@ This library ships with AI skills and agent workflows for [Claude Code](https://
 | **Skills** — API docs, locator strategy, function references | `.claude/skills/vasu-playwright-utils/` | Claude Code, Cursor |
 | **Playwright CLI skills** — browser automation commands      | `.claude/skills/playwright-cli/`        | Claude Code, Cursor |
 | **Agents** — test planner, generator, healer workflows       | `.claude/agents/`                       | Claude Code         |
+| **CLAUDE.md** — project instructions template                | `CLAUDE.md` (project root)              | Claude Code, Cursor |
 | **Cursor rules** — agent workflow rules with `@file` refs    | `.cursor/rules/`                        | Cursor              |
-| **CLAUDE.md loader** — links your `CLAUDE.md` into Cursor    | `.cursor/rules/project.mdc`             | Cursor              |
+| **CLAUDE.md loader** — links `CLAUDE.md` into Cursor         | `.cursor/rules/project.mdc`             | Cursor              |
 
-Files are **copied** (not symlinked) into your project. Both Claude Code and Cursor auto-discover `.claude/skills/`. Claude Code also auto-discovers `.claude/agents/`. Cursor uses `.cursor/rules/` to reference agent files. If your project has a `CLAUDE.md`, the setup also creates a Cursor rule that loads it via `@file CLAUDE.md`, so both tools share the same project instructions.
+Files are **copied** (not symlinked) into your project. Both Claude Code and Cursor auto-discover `.claude/skills/`. Claude Code also auto-discovers `.claude/agents/`. Cursor uses `.cursor/rules/` to reference agent files. The setup copies a `CLAUDE.md` template to your project root (skipped if one already exists) and creates a Cursor rule that loads it via `@file CLAUDE.md`, so both tools share the same project instructions.
 
 ### For consumers
 

agents/playwright-test-generator.md

@@ -92,10 +92,11 @@ For each test you generate:
 
 ## Required Test Structure
 
+**Preferred: Use project's page-setup** (automatically calls `setPage(page)` before each test):
+
 ```typescript
-import { test } from '@playwright/test';
+import { test } from '@pagesetup';
 import {
-  setPage,
   gotoURL,
   click,
   clickAndNavigate,
@@ -123,8 +124,7 @@ import {
 } from 'vasu-playwright-utils';
 
 test.describe('Test Suite Name', () => {
-  test('Test Case Name', async ({ page }) => {
-    setPage(page);
+  test('Test Case Name', async () => {
     // 1. Navigate to the application
     await gotoURL('https://example.com');
 
@@ -141,6 +141,8 @@ test.describe('Test Suite Name', () => {
 });
 ```
 
+**Fallback (standalone, when @pagesetup is not available):** Import `test` from `@playwright/test`, destructure `{ page }`, and call `setPage(page)` manually.
+
    <example-generation>
    For following plan:
 
@@ -166,12 +168,11 @@ Following file is generated:
 // spec: specs/plan.md
 // seed: tests/seed.spec.ts
 
-import { test } from '@playwright/test';
-import { setPage, gotoURL, fill, fillAndEnter, expectElementToBeVisible, getLocatorByPlaceholder } from 'vasu-playwright-utils';
+import { test } from '@pagesetup';
+import { gotoURL, fill, fillAndEnter, expectElementToBeVisible, getLocatorByPlaceholder } from 'vasu-playwright-utils';
 
 test.describe('Adding New Todos', () => {
-  test('Add Valid Todo', async ({ page }) => {
-    setPage(page);
+  test('Add Valid Todo', async () => {
     // 1. Click in the "What needs to be done?" input field
     await fill(getLocatorByPlaceholder('What needs to be done?'), 'Buy groceries');
 

agents/playwright-test-healer.md

@@ -125,7 +125,7 @@ Use standard Playwright CLI for running tests:
 - Document your findings and reasoning for each fix
 - Prefer robust, maintainable solutions over quick hacks
 - Use `vasu-playwright-utils` functions for all test code
-- Ensure `setPage(page)` is called in test setup before any utility functions
+- Ensure tests import `test` from `@pagesetup` or `@fixturesetup` (which call `setPage(page)` automatically). If using `@playwright/test` directly, `setPage(page)` must be called manually.
 - If multiple errors exist, fix them one at a time and retest
 - Provide clear explanations of what was broken and how you fixed it
 - Continue until the test runs successfully without any failures or errors

agents/playwright-test-planner.md

@@ -82,6 +82,7 @@ You will:
 - Include negative testing scenarios
 - Ensure scenarios are independent and can be run in any order
 - Reference `vasu-playwright-utils` functions in step descriptions so tests can be directly implemented
+- Follow the locator strategy priority in `references/locators.md` when noting selectors (prefer data-testid, role, label over CSS/XPath)
 
 **Output Format**: Save the complete test plan as a markdown file with clear headings, numbered steps, and
 professional formatting suitable for sharing with development and QA teams.

bin/setup.js

@@ -124,6 +124,27 @@ if (INSTALL_SKILLS) {
     path.join(cursorRulesDir, 'vasu-playwright-utils.mdc'),
     path.join(projectRoot, '.cursor', 'rules', 'vasu-playwright-utils.mdc'),
   );
+
+  // Copy CLAUDE.md template if consumer doesn't have one (or --force)
+  const claudeMdSrc = path.join(pkgDir, 'templates', 'CLAUDE.md');
+  if (fs.existsSync(claudeMdSrc)) {
+    const claudeMdDest = path.join(projectRoot, 'CLAUDE.md');
+    console.log(`\n${step++}. Installing CLAUDE.md template:`);
+    const rel = path.relative(projectRoot, claudeMdDest);
+    if (!FORCE && fs.existsSync(claudeMdDest)) {
+      console.log(`  [skip] ${rel} (exists, use --force to overwrite)`);
+    } else {
+      fs.copyFileSync(claudeMdSrc, claudeMdDest);
+      console.log(`  [copy] ${rel}`);
+    }
+  }
+
+  // Install CLAUDE.md loader for Cursor (so Cursor reads the same project instructions as Claude Code)
+  console.log(`\n${step++}. Linking CLAUDE.md for Cursor:`);
+  installCursorRule(
+    path.join(cursorRulesDir, 'project.mdc'),
+    path.join(projectRoot, '.cursor', 'rules', 'project.mdc'),
+  );
 }
 
 if (INSTALL_AGENTS) {
@@ -141,15 +162,6 @@ if (INSTALL_AGENTS) {
   );
 }
 
-// Install CLAUDE.md loader for Cursor (so Cursor reads the same project instructions as Claude Code)
-if (fs.existsSync(path.join(projectRoot, 'CLAUDE.md'))) {
-  console.log(`\n${step++}. Linking CLAUDE.md for Cursor:`);
-  installCursorRule(
-    path.join(cursorRulesDir, 'project.mdc'),
-    path.join(projectRoot, '.cursor', 'rules', 'project.mdc'),
-  );
-}
-
 // Summary
 console.log('\nDone! Installed to:');
 for (const p of installed) {

cursor-rules/project.mdc

@@ -1,5 +1,5 @@
 ---
-description: Project-wide instructions and conventions for vasu-playwright-utils
+description: Project-wide instructions and conventions
 globs: ["**/*"]
 ---
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "vasu-playwright-utils",
-  "version": "1.24.0",
+  "version": "1.24.1",
   "description": "Playwright Typescript Library with reusable utilities",
   "main": "./dist/src/vasu-playwright-lib/index.js",
   "types": "./dist/src/vasu-playwright-lib/index.d.ts",
@@ -49,7 +49,8 @@
     "skills",
     "agents",
     "cursor-rules",
-    "bin"
+    "bin",
+    "templates"
   ],
   "engines": {
     "node": ">=20.0.0"
@@ -80,6 +81,9 @@
   "peerDependencies": {
     "@playwright/test": ">=1.58.2"
   },
+  "overrides": {
+    "playwright": "^1.58.2"
+  },
   "scripts": {
     "ncu:check": "npx npm-check-updates --reject \"eslint,@eslint/js\" --dep prod,dev,optional,peer && npx npm-check-updates \"eslint,@eslint/js\" --target minor --deep peer",
     "ncu:update": "npx npm-check-updates --reject \"eslint,@eslint/js\" --dep prod,dev,optional,peer -u && npx npm-check-updates \"eslint,@eslint/js\" --target minor --deep peer -u",

package.json

@@ -4,7 +4,7 @@ Source: `src/vasu-playwright-lib/utils/locator-utils.ts`
 
 ## Locator Strategy Priority
 
-When choosing locators for test code, follow this priority order (best to worst). Always prefer the highest-priority strategy that uniquely identifies the element.
+When choosing locators for test code, follow this priority order (best to worst). **Prefer unique CSS or XPath with stable attributes over text-based locators** so that when a check fails you can tell quickly whether the element is missing (bug) or the copy changed (new functionality / locale).
 
 ### 1. `data-testid` attributes (Best)
 
@@ -23,8 +23,11 @@ Custom data attributes that carry stable, semantic meaning.
 // HTML: <div data-product-id="shoes-001">...</div>
 await click('[data-product-id="shoes-001"]');
 
-// HTML: <tr data-row-type="header">...</tr>
-await expectElementToBeVisible('[data-row-type="header"]');
+// HTML: <h2 data-test="complete-header">Thank you for your order</h2>
+const orderCompleteMessage = () => getLocator('[data-test="complete-header"]');
+await expectElementToContainText(orderCompleteMessage(), /thank you for your order/i, {
+  message: 'Checkout complete message should be displayed',
+});
 ```
 
 ### 3. `id` attributes
@@ -51,34 +54,9 @@ await fill('[name="email"]', 'user@example.com');
 await selectByText('[name="country"]', 'United States');
 ```
 
-### 5. Playwright built-in locators
+### 5. XPath with unique attributes
 
-Semantic locators that match how users perceive the page. Resilient to DOM changes.
-
-```typescript
-// By ARIA role + accessible name (preferred for interactive elements)
-await click(getLocatorByRole('button', { name: 'Submit' }));
-await fill(getLocatorByRole('textbox', { name: 'Email' }), 'user@example.com');
-await click(getLocatorByRole('link', { name: 'Sign up' }));
-await check(getLocatorByRole('checkbox', { name: 'Remember me' }));
-
-// By label text (preferred for form fields)
-await fill(getLocatorByLabel('Email address'), 'user@example.com');
-
-// By placeholder text
-await fill(getLocatorByPlaceholder('Search...'), 'playwright');
-
-// By visible text content
-await click(getLocatorByText('Add to cart'));
-
-// Use regex for partial or case-insensitive matching
-await click(getLocatorByRole('button', { name: /submit/i }));
-await click(getLocatorByText(/view details/i));
-```
-
-### 6. XPath with unique attributes
-
-Use only when higher-priority strategies are unavailable. Target stable attributes.
+Use when no data-_ or id is available. Target **stable attributes** (e.g. `data-test`, `aria-_`, `type`), not text.
 
 ```typescript
 // Good: XPath with stable attributes
@@ -89,9 +67,9 @@ await click('//input[@type="email"]');
 await click('//div[@data-section="billing"]//button[@type="submit"]');
 ```
 
-### 7. CSS with unique attributes
+### 6. CSS with unique attributes
 
-Similar to XPath — use stable attributes, not structural position.
+Use stable attribute selectors so the locator does not depend on copy or locale.
 
 ```typescript
 // Good: attribute-based CSS
@@ -100,6 +78,42 @@ await fill('input[type="email"]', 'user@example.com');
 
 // Good: scoped by stable parent
 await click('.billing-section button[type="submit"]');
+
+// Good: data-test (e.g. Sauce Demo checkout complete)
+const orderCompleteMessage = () => getLocator('[data-test="complete-header"]');
+await expectElementToContainText(orderCompleteMessage(), /thank you for your order/i);
+```
+
+### 7. Playwright built-in locators (role / text) — use only when no stable selector exists
+
+Text- and role-based locators are **flaky**: they change with copy, locale, and country. If the only way to find an element is by its text, a failure does not tell you whether the element is missing (bug) or the wording changed (new feature / i18n). Prefer **data-testid**, **data-\***, **id**, or **unique CSS/XPath** first.
+
+When you must use role or text:
+
+```typescript
+// By ARIA role + accessible name
+await click(getLocatorByRole('button', { name: 'Submit' }));
+await fill(getLocatorByRole('textbox', { name: 'Email' }), 'user@example.com');
+
+// By label text (form fields)
+await fill(getLocatorByLabel('Email address'), 'user@example.com');
+
+// By placeholder text
+await fill(getLocatorByPlaceholder('Search...'), 'playwright');
+
+// By visible text — avoid for assertions; use stable selector + assert text separately
+await click(getLocatorByText('Add to cart'));
+```
+
+**Assertions:** Prefer a **stable locator** for the element and assert the **text in the assertion**. That way a failure shows "expected text X, got Y" (copy change) vs element not found (bug).
+
+```typescript
+// Prefer: stable selector + text in assertion
+const orderCompleteMessage = () => getLocator('[data-test="complete-header"]');
+await expectElementToContainText(orderCompleteMessage(), /thank you for your order/i);
+
+// Avoid: locating by text — fails ambiguously if copy or locale changes
+// const orderCompleteMessage = () => getLocatorByRole('heading', { name: /thank you for your order/i });
 ```
 
 ### 8. XPath (structural)