playwright-toolbox 1.0.0

package/packages/pw-standard/src/eslint/rules/require-test-description.ts

@@ -0,0 +1,159 @@
+import { Rule } from 'eslint';
+import { CallExpression, Literal, TemplateLiteral } from 'estree';
+import { RuleModule } from '../types';
+
+const TEST_FUNCTIONS = new Set(['test', 'it']);
+
+const VAGUE_PATTERNS: RegExp[] = [
+	/^test\s*\d*$/i,
+	/^it\s*\d*$/i,
+	/^spec\s*\d*$/i,
+	/^(todo|fixme|wip)$/i,
+	/^\d+$/,
+];
+
+const MIN_DESCRIPTION_LENGTH = 10;
+const TEST_ID_AT_END_PATTERN = /\bnrt-\d+\s*$/i;
+
+function getMeaningfulDescription(description: string): string {
+	return description
+		.replace(TEST_ID_AT_END_PATTERN, '')
+		.replace(/\s+/g, ' ')
+		.trim();
+}
+
+const rule: RuleModule = {
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Require meaningful, descriptive test names',
+			category: 'Best Practices',
+			recommended: true,
+			url: 'https://github.com/acahet-automation-org/playwright-standards/blob/main/docs/rules/require-test-description.md',
+		},
+		messages: {
+			missingDescription:
+				'test() must have a description as the first argument.',
+			missingTestId:
+				'Test description "{{name}}" must end with a test ID in the format nrt-123.',
+			tooShort:
+				'Test description "{{name}}" is too short (min {{min}} characters). Describe observable behaviour.',
+			vagueDescription:
+				'Test description "{{name}}" is too vague. Describe what the user sees or does.',
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					minLength: { type: 'number', minimum: 1 },
+				},
+				additionalProperties: false,
+			},
+		],
+	},
+
+	create(context: Rule.RuleContext): Rule.RuleListener {
+		const options = context.options[0] ?? {};
+		const minLength: number = options.minLength ?? MIN_DESCRIPTION_LENGTH;
+
+		return {
+			CallExpression(node: CallExpression) {
+				if (node.callee.type !== 'Identifier') return;
+				const name = (node.callee as { name: string }).name;
+				if (!TEST_FUNCTIONS.has(name)) return;
+
+				const firstArg = node.arguments[0];
+
+				if (!firstArg) {
+					context.report({ node, messageId: 'missingDescription' });
+					return;
+				}
+
+				if (firstArg.type === 'TemplateLiteral') {
+					const cooked = (firstArg as TemplateLiteral).quasis
+						.map((q) => q.value.cooked ?? '')
+						.join('');
+					const description = cooked.trim();
+					const meaningfulDescription =
+						getMeaningfulDescription(description);
+
+					if (!TEST_ID_AT_END_PATTERN.test(description)) {
+						context.report({
+							node: firstArg,
+							messageId: 'missingTestId',
+							data: { name: description },
+						});
+						return;
+					}
+
+					if (
+						VAGUE_PATTERNS.some((pattern) =>
+							pattern.test(meaningfulDescription),
+						)
+					) {
+						context.report({
+							node: firstArg,
+							messageId: 'vagueDescription',
+							data: { name: meaningfulDescription },
+						});
+						return;
+					}
+
+					if (meaningfulDescription.length < minLength) {
+						context.report({
+							node: firstArg,
+							messageId: 'tooShort',
+							data: {
+								name: meaningfulDescription,
+								min: String(minLength),
+							},
+						});
+					}
+					return;
+				}
+
+				if (firstArg.type !== 'Literal') return;
+
+				const description = String((firstArg as Literal).value).trim();
+				const meaningfulDescription =
+					getMeaningfulDescription(description);
+
+				if (!TEST_ID_AT_END_PATTERN.test(description)) {
+					context.report({
+						node: firstArg,
+						messageId: 'missingTestId',
+						data: { name: description },
+					});
+					return;
+				}
+
+				if (
+					VAGUE_PATTERNS.some((pattern) =>
+						pattern.test(meaningfulDescription),
+					)
+				) {
+					context.report({
+						node: firstArg,
+						messageId: 'vagueDescription',
+						data: { name: meaningfulDescription },
+					});
+					return;
+				}
+
+				if (meaningfulDescription.length < minLength) {
+					context.report({
+						node: firstArg,
+						messageId: 'tooShort',
+						data: {
+							name: meaningfulDescription,
+							min: String(minLength),
+						},
+					});
+					return;
+				}
+			},
+		};
+	},
+};
+
+export default rule;

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

@@ -0,0 +1,20 @@
+import { Rule } from 'eslint';
+
+export interface RuleModule extends Rule.RuleModule {
+	meta: Rule.RuleMetaData & {
+		docs: {
+			description: string;
+			category: string;
+			recommended: boolean;
+			url?: string;
+		};
+	};
+}
+
+export type RuleMap = Record<string, RuleModule>;
+
+export type Severity = 'error' | 'warn' | 'off';
+
+export interface ConfigRules {
+	[ruleName: string]: Severity | [Severity, ...unknown[]];
+}

package/packages/pw-standard/src/eslint/utils/ast.ts

@@ -0,0 +1,59 @@
+import { Rule } from 'eslint';
+import { Node, CallExpression, MemberExpression, Identifier } from 'estree';
+
+export function isPlaywrightFile(filename: string): boolean {
+	return (
+		/\.(spec|test)\.[jt]sx?$/.test(filename) ||
+		/[/\\](e2e|tests?)[/\\]/.test(filename)
+	);
+}
+
+export function isWaitForTimeout(node: CallExpression): boolean {
+	if (node.callee.type !== 'MemberExpression') return false;
+	const callee = node.callee as MemberExpression;
+	return (
+		callee.property.type === 'Identifier' &&
+		(callee.property as Identifier).name === 'waitForTimeout'
+	);
+}
+
+export function getMethodName(node: CallExpression): string | null {
+	if (node.callee.type !== 'MemberExpression') return null;
+	const prop = (node.callee as MemberExpression).property;
+	return prop.type === 'Identifier' ? (prop as Identifier).name : null;
+}
+
+export function getObjectName(node: CallExpression): string | null {
+	if (node.callee.type !== 'MemberExpression') return null;
+	const obj = (node.callee as MemberExpression).object;
+	return obj.type === 'Identifier' ? (obj as Identifier).name : null;
+}
+
+export function findAncestor(
+	node: Node,
+	context: Rule.RuleContext,
+	predicate: (n: Node) => boolean,
+): Node | null {
+	const ancestors = context.getAncestors();
+	for (let i = ancestors.length - 1; i >= 0; i--) {
+		if (predicate(ancestors[i])) return ancestors[i];
+	}
+	return null;
+}
+
+export const BRITTLE_SELECTOR_PATTERNS: RegExp[] = [
+	/^\.[\w-]+/,
+	/^#[\w-]+/,
+	/nth-child/,
+	/nth-of-type/,
+	/^\/\//,
+	/\s*>\s*/,
+	/\s*\+\s*/,
+	/\s*~\s*/,
+];
+
+export function isBrittleSelector(selector: string): boolean {
+	return BRITTLE_SELECTOR_PATTERNS.some((pattern) =>
+		pattern.test(selector.trim()),
+	);
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @acahet/pw-standard
+ *
+ * Root barrel. Prefer importing from the specific entry point
+ * to keep bundle size small:
+ *
+ *   import plugin  from '@acahet/pw-standard/eslint'
+ *   import { baseConfig } from '@acahet/pw-standard/playwright'
+ *   import { BasePage }   from '@acahet/pw-standard/base'
+ *
+ * This barrel is available for tooling that needs everything at once.
+ */
+export { default as eslintPlugin } from './eslint/index';

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

@@ -0,0 +1,6 @@
+/**
+ * Backwards-compatible bridge export.
+ *
+ * New consumers should import from `@acahet/playwright-config` directly.
+ */
+export * from '@acahet/playwright-config';

package/packages/pw-standard/src/tsconfig/base.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "@acahet/pw-standard — base",
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020", "DOM"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}

package/packages/pw-standard/src/tsconfig/strict.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "@acahet/pw-standard — strict",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUncheckedIndexedAccess": true
+  }
+}

package/packages/pw-standard/tests/eslint/no-brittle-selectors.test.ts

@@ -0,0 +1,34 @@
+import { RuleTester } from 'eslint';
+import rule from '../../src/eslint/rules/no-brittle-selectors';
+
+const tester = new RuleTester({
+	parserOptions: { ecmaVersion: 2020, sourceType: 'module' },
+});
+
+tester.run('no-brittle-selectors', rule, {
+	valid: [
+		{
+			code: `async function t() { await page.getByTestId('submit-button').click(); }`,
+		},
+		{
+			code: `async function t() { await page.getByRole('button', { name: 'Submit' }).click(); }`,
+		},
+		{
+			code: `async function t() { await page.locator('[data-testid="modal"]').click(); }`,
+		},
+	],
+	invalid: [
+		{
+			code: `async function t() { await page.locator('.btn-primary').click(); }`,
+			errors: [{ messageId: 'brittleSelector' }],
+		},
+		{
+			code: `async function t() { await page.locator('#submit-btn').click(); }`,
+			errors: [{ messageId: 'brittleSelector' }],
+		},
+		{
+			code: `async function t() { await page.locator('div > span > button').click(); }`,
+			errors: [{ messageId: 'brittleSelector' }],
+		},
+	],
+});

package/packages/pw-standard/tests/eslint/no-page-pause-and-focused.test.ts

@@ -0,0 +1,41 @@
+import { RuleTester } from 'eslint';
+import noPagePause from '../../src/eslint/rules/no-page-pause';
+import noFocusedTests from '../../src/eslint/rules/no-focused-tests';
+
+const tester = new RuleTester({
+	parserOptions: { ecmaVersion: 2020, sourceType: 'module' },
+});
+
+tester.run('no-page-pause', noPagePause, {
+	valid: [{ code: `async function t() { await page.goto('/'); }` }],
+	invalid: [
+		{
+			code: `async function t() { await page.pause(); }`,
+			errors: [{ messageId: 'noPagePause' }],
+		},
+	],
+});
+
+tester.run('no-focused-tests', noFocusedTests, {
+	valid: [
+		{ code: `test('a normal test', async () => {});` },
+		{
+			code: `test.skip('skipped test', async () => {});`,
+			options: [{ allowSkip: true }],
+		},
+	],
+	invalid: [
+		{
+			code: `test.only('focused test', async () => {});`,
+			errors: [{ messageId: 'noOnly' }],
+		},
+		{
+			code: `describe.only('focused describe', () => {});`,
+			errors: [{ messageId: 'noOnly' }],
+		},
+		{
+			code: `test.skip('skipped test', async () => {});`,
+			errors: [{ messageId: 'noSkip' }],
+		},
+	],
+});

package/packages/pw-standard/tests/eslint/no-wait-for-timeout.test.ts

@@ -0,0 +1,30 @@
+import { RuleTester } from 'eslint';
+import rule from '../../src/eslint/rules/no-wait-for-timeout';
+
+const tester = new RuleTester({
+	parserOptions: { ecmaVersion: 2020, sourceType: 'module' },
+});
+
+tester.run('no-wait-for-timeout', rule, {
+	valid: [
+		{
+			code: `async function t() { await page.locator('[data-testid="modal"]').waitFor(); }`,
+		},
+		{
+			code: `async function t() { await expect(page.getByTestId('spinner')).toBeHidden(); }`,
+		},
+		{
+			code: `async function t() { await page.waitForResponse(r => r.url().includes('/api')); }`,
+		},
+	],
+	invalid: [
+		{
+			code: `async function t() { await page.waitForTimeout(2000); }`,
+			errors: [{ messageId: 'noWaitForTimeout' }],
+		},
+		{
+			code: `async function t() { await frame.waitForTimeout(500); }`,
+			errors: [{ messageId: 'noWaitForTimeout' }],
+		},
+	],
+});

package/packages/pw-standard/tests/eslint/prefer-web-first-assertions.test.ts

@@ -0,0 +1,25 @@
+import { RuleTester } from 'eslint';
+import rule from '../../src/eslint/rules/prefer-web-first-assertions';
+
+const tester = new RuleTester({
+	parserOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+
+tester.run('prefer-web-first-assertions', rule, {
+	valid: [
+		{
+			code: `await expect(page.getByTestId('title')).toHaveText('Hello');`,
+		},
+		{ code: `const text = await page.locator('h1').innerText();` },
+	],
+	invalid: [
+		{
+			code: `expect(await page.locator('h1').innerText()).toBe('Hello');`,
+			errors: [{ messageId: 'preferWebFirst' }],
+		},
+		{
+			code: `expect(await page.locator('button').isVisible()).toBe(true);`,
+			errors: [{ messageId: 'preferWebFirst' }],
+		},
+	],
+});

package/packages/pw-standard/tests/eslint/require-test-description.test.ts

@@ -0,0 +1,49 @@
+import { RuleTester } from 'eslint';
+import rule from '../../src/eslint/rules/require-test-description';
+
+const tester = new RuleTester({
+	parserOptions: { ecmaVersion: 2020, sourceType: 'module' },
+});
+
+tester.run('require-test-description', rule, {
+	valid: [
+		{
+			code: `test('user can submit the login form with valid credentials nrt-101', async () => {});`,
+		},
+		{
+			code: `it('admin sees the delete button when viewing another user nrt-202', async () => {});`,
+		},
+		{
+			// custom minLength option
+			code: `test('okay nrt-303', async () => {});`,
+			options: [{ minLength: 3 }],
+		},
+	],
+	invalid: [
+		{
+			// only test ID at the end leaves no meaningful description → tooShort
+			code: `test('nrt-1', async () => {});`,
+			errors: [{ messageId: 'tooShort' }],
+		},
+		{
+			// missing nrt-xxx suffix → missingTestId
+			code: `test('user can submit the login form with valid credentials', async () => {});`,
+			errors: [{ messageId: 'missingTestId' }],
+		},
+		{
+			// id not at the end → missingTestId
+			code: `test('nrt-404 user can submit the login form with valid credentials', async () => {});`,
+			errors: [{ messageId: 'missingTestId' }],
+		},
+		{
+			// matches VAGUE_PATTERNS after removing trailing test ID → vagueDescription
+			code: `test('fixme nrt-404', async () => {});`,
+			errors: [{ messageId: 'vagueDescription' }],
+		},
+		{
+			// matches /^test\s*\d*$/i after removing trailing test ID → vagueDescription
+			code: `test('test      1 nrt-505', async () => {});`,
+			errors: [{ messageId: 'vagueDescription' }],
+		},
+	],
+});

package/packages/pw-standard/tsconfig.json

@@ -0,0 +1,24 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "commonjs",
+		"lib": ["ES2020"],
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"paths": {
+			"@acahet/pw-standard/eslint": ["./src/eslint/index.ts"],
+			"@acahet/pw-standard/playwright": ["./src/playwright/index.ts"],
+			"@acahet/pw-standard/base": ["./src/base/index.ts"]
+		}
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "tests"]
+}