playwright-toolbox 1.0.0

package/packages/pw-standard/CHANGELOG.md

@@ -0,0 +1,31 @@
+# @acahet/pw-standard
+
+## 3.0.0
+
+### Minor Changes
+
+- 51cd994: feat: publish history dashboard to npm, extract playwright-config as standalone package, add missing .eslintrc.js to pw-standard
+
+### Patch Changes
+
+- Updated dependencies [51cd994]
+  - @acahet/playwright-config@1.2.0
+
+## 2.0.0
+
+### Minor Changes
+
+- 4329be3: Convert repository to npm workspaces with three independent packages and introduce `@acahet/playwright-config`.
+
+  Summary:
+
+  - migrate to `packages/*` workspace structure
+  - split Playwright config into dedicated package
+  - keep a compatibility bridge export at `@acahet/pw-standard/playwright`
+  - update dashboard package metadata/docs for new workspace location
+  - add root orchestration scripts and Changesets configuration
+
+### Patch Changes
+
+- Updated dependencies [4329be3]
+  - @acahet/playwright-config@1.1.0

package/packages/pw-standard/README.md

@@ -0,0 +1,50 @@
+# @acahet/pw-standard
+
+Shared Playwright standards package:
+
+- ESLint plugin and custom rules
+- base classes/fixtures entrypoint
+- shared tsconfig presets
+- compatibility bridge export for Playwright config (`@acahet/pw-standard/playwright`)
+
+## Install
+
+```bash
+npm i -D @acahet/pw-standard
+```
+
+## Usage
+
+### ESLint plugin
+
+```ts
+import plugin from '@acahet/pw-standard/eslint';
+
+export default [
+	{
+		plugins: {
+			'playwright-standards': plugin,
+		},
+		rules: {
+			'playwright-standards/no-wait-for-timeout': 'error',
+			'playwright-standards/no-brittle-selectors': 'error',
+		},
+	},
+];
+```
+
+### TSConfig preset
+
+```json
+{
+	"extends": "@acahet/pw-standard/tsconfig/base"
+}
+```
+
+### Playwright config compatibility export
+
+```ts
+import * as configPreset from '@acahet/pw-standard/playwright';
+```
+
+New projects should import Playwright config presets from `@acahet/playwright-config` directly.

package/packages/pw-standard/jest.config.js

@@ -0,0 +1,28 @@
+/** @type {import('jest').Config} */
+const config = {
+	preset: 'ts-jest',
+	testEnvironment: 'node',
+	roots: ['<rootDir>/tests'],
+	testMatch: ['**/*.test.ts'],
+	moduleNameMapper: {
+		'^@acahet/pw-standard/eslint$': '<rootDir>/src/eslint/index.ts',
+		'^@acahet/pw-standard/playwright$': '<rootDir>/src/playwright/index.ts',
+		'^@acahet/pw-standard/base$': '<rootDir>/src/base/index.ts',
+	},
+	collectCoverageFrom: [
+		'src/**/*.ts',
+		'!src/**/*.d.ts',
+		'!src/**/index.ts', // barrel files — covered transitively
+		'!src/tsconfig/**',
+	],
+	coverageThreshold: {
+		global: {
+			branches: 80,
+			functions: 80,
+			lines: 80,
+			statements: 80,
+		},
+	},
+};
+
+module.exports = config;

package/packages/pw-standard/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@acahet/pw-standard",
+  "version": "3.0.0",
+  "description": "Shared Playwright + TypeScript standards: ESLint rules, configs, base classes and fixtures",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./eslint": {
+      "import": "./dist/eslint/index.js",
+      "require": "./dist/eslint/index.js",
+      "types": "./dist/eslint/index.d.ts"
+    },
+    "./playwright": {
+      "import": "./dist/playwright/index.js",
+      "require": "./dist/playwright/index.js",
+      "types": "./dist/playwright/index.d.ts"
+    },
+    "./tsconfig/base": "./src/tsconfig/base.json",
+    "./tsconfig/strict": "./src/tsconfig/strict.json",
+    "./base": {
+      "import": "./dist/base/index.js",
+      "require": "./dist/base/index.js",
+      "types": "./dist/base/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src/tsconfig",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "build:watch": "tsc --project tsconfig.json --watch",
+    "test": "jest --config jest.config.js",
+    "test:watch": "jest --config jest.config.js --watch",
+    "test:coverage": "jest --config jest.config.js --coverage",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "playwright",
+    "typescript",
+    "testing",
+    "e2e",
+    "standards"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acahet-automation-org/playwright-toolbox.git",
+    "directory": "packages/pw-standard"
+  },
+  "peerDependencies": {
+    "eslint": ">=8.0.0",
+    "@playwright/test": ">=1.40.0",
+    "@acahet/playwright-config": ">=1.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.42.0",
+    "@types/eslint": "^8.56.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/packages/pw-standard/src/base/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @acahet/pw-standard/base
+ *
+ * Shared base classes and fixtures for Playwright test suites.
+ *
+ * Usage:
+ *
+ *   import { BasePage } from '@acahet/pw-standard/base';
+ *
+ *   export class LoginPage extends BasePage {
+ *     async goto() { await this.page.goto('/login'); }
+ *   }
+ */
+
+// Base classes will be added here — e.g.:
+// export { BasePage }    from './BasePage';
+// export { BaseFixture } from './BaseFixture';
+
+export {};

package/packages/pw-standard/src/eslint/index.ts

@@ -0,0 +1,91 @@
+import { RuleMap, ConfigRules } from './types';
+import noWaitForTimeout from './rules/no-wait-for-timeout';
+import noBrittleSelectors from './rules/no-brittle-selectors';
+import requireTestDescription from './rules/require-test-description';
+import noPagePause from './rules/no-page-pause';
+import noFocusedTests from './rules/no-focused-tests';
+import preferWebFirstAssertions from './rules/prefer-web-first-assertions';
+
+// ─── Rule registry ────────────────────────────────────────────────────────────
+// Add new rules here — they are automatically picked up by all configs below.
+
+const rules: RuleMap = {
+	'no-wait-for-timeout': noWaitForTimeout,
+	'no-brittle-selectors': noBrittleSelectors,
+	'require-test-description': requireTestDescription,
+	'no-page-pause': noPagePause,
+	'no-focused-tests': noFocusedTests,
+	'prefer-web-first-assertions': preferWebFirstAssertions,
+};
+
+// ─── Shared parser options ────────────────────────────────────────────────────
+
+const PARSER_OPTIONS = {
+	ecmaVersion: 2020,
+	sourceType: 'module' as const,
+};
+
+// ─── Helper: prefix all rule keys with the plugin name ───────────────────────
+
+function prefixedRules(severity: 'error' | 'warn'): ConfigRules {
+	return Object.keys(rules).reduce<ConfigRules>((acc, key) => {
+		const meta = rules[key].meta;
+		if (meta.docs?.recommended) {
+			acc[`playwright-standards/${key}`] = severity;
+		}
+		return acc;
+	}, {});
+}
+
+// ─── Configs ──────────────────────────────────────────────────────────────────
+
+const configs = {
+	/**
+	 * `recommended` — all recommended rules as errors.
+	 * Best for CI enforcement.
+	 */
+	recommended: {
+		plugins: ['playwright-standards'],
+		parserOptions: PARSER_OPTIONS,
+		rules: prefixedRules('error'),
+	},
+
+	/**
+	 * `strict` — all rules (including non-recommended) as errors.
+	 */
+	strict: {
+		plugins: ['playwright-standards'],
+		parserOptions: PARSER_OPTIONS,
+		rules: Object.keys(rules).reduce<ConfigRules>((acc, key) => {
+			acc[`playwright-standards/${key}`] = 'error';
+			return acc;
+		}, {}),
+	},
+
+	/**
+	 * `warn` — all recommended rules as warnings.
+	 * Useful when adopting the plugin incrementally.
+	 */
+	warn: {
+		plugins: ['playwright-standards'],
+		parserOptions: PARSER_OPTIONS,
+		rules: prefixedRules('warn'),
+	},
+};
+
+// ─── Plugin export ────────────────────────────────────────────────────────────
+
+const plugin = {
+	meta: {
+		name: '@acahet/pw-standard',
+		version: '1.0.0',
+	},
+	rules,
+	configs,
+};
+
+export default plugin;
+
+// Named exports for consumers who import rules individually
+export { rules, configs };
+export type { RuleMap, ConfigRules };

package/packages/pw-standard/src/eslint/rules/no-brittle-selectors.ts

@@ -0,0 +1,53 @@
+import { Rule } from 'eslint';
+import { CallExpression, Literal } from 'estree';
+import { getMethodName, isBrittleSelector } from '../utils/ast';
+import { RuleModule } from '../types';
+
+const LOCATOR_METHODS = new Set([
+	'locator',
+	'$',
+	'$$',
+	'waitForSelector',
+	'querySelector',
+]);
+
+const rule: RuleModule = {
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description:
+				'Discourage brittle CSS / XPath selectors — prefer getByTestId, getByRole, getByLabel, etc.',
+			category: 'Best Practices',
+			recommended: true,
+			url: 'https://github.com/acahet-automation-org/playwright-standards/blob/main/docs/rules/no-brittle-selectors.md',
+		},
+		messages: {
+			brittleSelector:
+				'Brittle selector "{{selector}}". Prefer getByTestId(), getByRole(), getByLabel(), or getByText() instead.',
+		},
+		schema: [],
+	},
+
+	create(context: Rule.RuleContext): Rule.RuleListener {
+		return {
+			CallExpression(node: CallExpression) {
+				const method = getMethodName(node);
+				if (!method || !LOCATOR_METHODS.has(method)) return;
+
+				const firstArg = node.arguments[0];
+				if (!firstArg || firstArg.type !== 'Literal') return;
+
+				const selector = String((firstArg as Literal).value);
+				if (isBrittleSelector(selector)) {
+					context.report({
+						node: firstArg,
+						messageId: 'brittleSelector',
+						data: { selector },
+					});
+				}
+			},
+		};
+	},
+};
+
+export default rule;

package/packages/pw-standard/src/eslint/rules/no-focused-tests.ts

@@ -0,0 +1,61 @@
+import { Rule } from 'eslint';
+import { CallExpression, MemberExpression, Identifier } from 'estree';
+import { RuleModule } from '../types';
+
+const FOCUSED_METHODS = new Set(['only', 'skip']);
+const TEST_DESCRIBE_OBJECTS = new Set(['test', 'it', 'describe']);
+
+const rule: RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow test.only() / describe.only() — remove before committing',
+      category: 'Best Practices',
+      recommended: true,
+      url: 'https://github.com/acahet-automation-org/playwright-standards/blob/main/docs/rules/no-focused-tests.md',
+    },
+    messages: {
+      noOnly: '"{{parent}}.only()" found. Remove it before committing to avoid blocking the full test suite.',
+      noSkip: '"{{parent}}.skip()" found. Remove or resolve the skip before committing.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowSkip: { type: 'boolean' },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    const options = context.options[0] ?? {};
+    const allowSkip: boolean = options.allowSkip ?? false;
+
+    return {
+      CallExpression(node: CallExpression) {
+        if (node.callee.type !== 'MemberExpression') return;
+        const callee = node.callee as MemberExpression;
+
+        if (callee.object.type !== 'Identifier') return;
+        const parentName = (callee.object as Identifier).name;
+        if (!TEST_DESCRIBE_OBJECTS.has(parentName)) return;
+
+        if (callee.property.type !== 'Identifier') return;
+        const methodName = (callee.property as Identifier).name;
+        if (!FOCUSED_METHODS.has(methodName)) return;
+
+        if (methodName === 'skip' && allowSkip) return;
+
+        context.report({
+          node,
+          messageId: methodName === 'only' ? 'noOnly' : 'noSkip',
+          data: { parent: parentName },
+        });
+      },
+    };
+  },
+};
+
+export default rule;

package/packages/pw-standard/src/eslint/rules/no-page-pause.ts

@@ -0,0 +1,37 @@
+import { Rule } from 'eslint';
+import { CallExpression, MemberExpression, Identifier } from 'estree';
+import { RuleModule } from '../types';
+
+const rule: RuleModule = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow page.pause() — remove before committing',
+			category: 'Best Practices',
+			recommended: true,
+			url: 'https://github.com/acahet-automation-org/playwright-standards/blob/main/docs/rules/no-page-pause.md',
+		},
+		messages: {
+			noPagePause:
+				'page.pause() is for local debugging only. Remove it before committing.',
+		},
+		schema: [],
+	},
+
+	create(context: Rule.RuleContext): Rule.RuleListener {
+		return {
+			CallExpression(node: CallExpression) {
+				if (node.callee.type !== 'MemberExpression') return;
+				const callee = node.callee as MemberExpression;
+				if (
+					callee.property.type === 'Identifier' &&
+					(callee.property as Identifier).name === 'pause'
+				) {
+					context.report({ node, messageId: 'noPagePause' });
+				}
+			},
+		};
+	},
+};
+
+export default rule;

package/packages/pw-standard/src/eslint/rules/no-wait-for-timeout.ts

@@ -0,0 +1,34 @@
+import { Rule } from 'eslint';
+import { CallExpression } from 'estree';
+import { isWaitForTimeout } from '../utils/ast';
+import { RuleModule } from '../types';
+
+const rule: RuleModule = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow waitForTimeout() — use explicit wait conditions instead',
+			category: 'Best Practices',
+			recommended: true,
+			url: 'https://github.com/acahet-automation-org/playwright-standards/blob/main/docs/rules/no-wait-for-timeout.md',
+		},
+		messages: {
+			noWaitForTimeout:
+				'Avoid waitForTimeout(). Use waitFor(), waitForResponse(), or expect(...).toBeVisible() instead.',
+		},
+		schema: [],
+	},
+
+	create(context: Rule.RuleContext): Rule.RuleListener {
+		return {
+			CallExpression(node: CallExpression) {
+				if (isWaitForTimeout(node)) {
+					context.report({ node, messageId: 'noWaitForTimeout' });
+				}
+			},
+		};
+	},
+};
+
+export default rule;

package/packages/pw-standard/src/eslint/rules/prefer-web-first-assertions.ts

@@ -0,0 +1,90 @@
+import { Rule } from 'eslint';
+import { CallExpression, Identifier } from 'estree';
+import { RuleModule } from '../types';
+
+const EAGER_METHODS = new Set([
+	'innerText',
+	'textContent',
+	'getAttribute',
+	'isVisible',
+	'isHidden',
+	'isEnabled',
+	'isDisabled',
+	'isChecked',
+	'inputValue',
+	'innerHTML',
+]);
+
+const PREFERRED: Record<string, string> = {
+	innerText: 'toHaveText()',
+	textContent: 'toHaveText()',
+	getAttribute: 'toHaveAttribute()',
+	isVisible: 'toBeVisible()',
+	isHidden: 'toBeHidden()',
+	isEnabled: 'toBeEnabled()',
+	isDisabled: 'toBeDisabled()',
+	isChecked: 'toBeChecked()',
+	inputValue: 'toHaveValue()',
+	innerHTML: 'toContainText() or toHaveText()',
+};
+
+const rule: RuleModule = {
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description:
+				'Prefer Playwright web-first assertions over awaited property calls',
+			category: 'Best Practices',
+			recommended: true,
+			url: 'https://github.com/acahet-automation-org/playwright-standards/blob/main/docs/rules/prefer-web-first-assertions.md',
+		},
+		messages: {
+			preferWebFirst:
+				'Avoid awaiting "{{method}}()" inside expect(). Use the web-first assertion "{{preferred}}" instead — it auto-retries.',
+		},
+		schema: [],
+	},
+
+	create(context: Rule.RuleContext): Rule.RuleListener {
+		const sourceCode = context.sourceCode;
+
+		return {
+			'CallExpression > AwaitExpression > CallExpression'(
+				node: CallExpression,
+			) {
+				if (node.callee.type !== 'MemberExpression') return;
+				const prop = node.callee.property;
+				if (prop.type !== 'Identifier') return;
+
+				const method = (prop as Identifier).name;
+				if (!EAGER_METHODS.has(method)) return;
+
+				const ancestors = sourceCode.getAncestors(node);
+				const awaitExpr = ancestors[ancestors.length - 1];
+				if (!awaitExpr || awaitExpr.type !== 'AwaitExpression') return;
+
+				const outerCall = ancestors[ancestors.length - 2];
+				if (
+					!outerCall ||
+					outerCall.type !== 'CallExpression' ||
+					(outerCall as CallExpression).callee.type !==
+						'Identifier' ||
+					((outerCall as CallExpression).callee as Identifier)
+						.name !== 'expect'
+				)
+					return;
+
+				context.report({
+					node,
+					messageId: 'preferWebFirst',
+					data: {
+						method,
+						preferred: PREFERRED[method] ?? 'a web-first assertion',
+					},
+				});
+			},
+		};
+	},
+};
+
+export default rule;