@autotests/playwright-impact 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Alex Kiselev
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,117 +1,149 @@
-# test-impact-core
+# Playwright Spec Impact
 
-Select only impacted Playwright specs from changed POM and utility methods.
+If you use Playwright + POM and your CI runs are slow, this library selects only specs affected by your changes.
 
-`test-impact-core` is built for Playwright teams using Page Object Model who want faster feedback and shorter CI cycles without running the full test suite on every commit.
-
-It solves a common problem: broad reruns after small UI/POM changes. Instead of running everything, it computes the smallest reliable spec set to execute.
+It reads changed files, finds impacted specs, and helps you run only what matters.
 
 ## Install
 
 ```bash
 // npm
-npm i @autotests/test-impact-core
+npm i @autotests/playwright-impact
 
 // pnpm
-pnpm add @autotests/test-impact-core
+pnpm add @autotests/playwright-impact
 ```
 
-## Why
+## Quick Start (Copy & Run)
 
-- Large Playwright projects grow quickly, and full-suite runs become expensive.
-- POM-heavy repositories often change in narrow areas but still trigger wide test execution.
-- Running all specs for each PR slows CI, delays triage, and increases infrastructure cost.
-- `test-impact-core` changes this by selecting only specs impacted by changed files and changed method behavior.
+### Minimal working code
 
-## 30-Second Setup (Minimum Required Configuration)
+Create `impact.js` in your repo root:
 
-Only these fields are required. Everything else has defaults.
+```js
+const { analyzeImpactedSpecs } = require('@autotests/playwright-impact');
 
-- `repoRoot`: absolute path to repository root.
-- `profile.testsRootRelative`: where Playwright specs live.
-- `profile.changedSpecPrefix`: prefix used to detect directly changed spec files.
-- `profile.isRelevantPomPath(filePath)`: rule that marks which source files are considered POM/utility inputs for impact analysis.
+const result = analyzeImpactedSpecs({
+  repoRoot: process.cwd(),
+  profile: {
+    testsRootRelative: 'tests',
+    changedSpecPrefix: 'tests/',
+    isRelevantPomPath: (filePath) =>
+      (filePath.startsWith('src/pages/') || filePath.startsWith('src/utils/')) &&
+      (filePath.endsWith('.ts') || filePath.endsWith('.tsx')),
+  },
+});
 
-Public API entry point: `analyzeImpactedSpecs`.
+if (!result.hasAnythingToRun) {
+  console.log('No impacted specs found');
+  process.exit(0);
+}
 
-## Typical CI Usage
+for (const spec of result.selectedSpecsRelative) {
+  console.log(spec);
+}
+```
 
-Typical workflow in CI:
+Save as `impact.js`
 
-1. Compare feature branch changes against `main` (via `baseRef`).
-2. Compute impacted specs.
-3. Exit early when `hasAnythingToRun` is false.
-4. Run only `selectedSpecsRelative` in Playwright.
+Run: `node impact.js`
 
-This pattern reduces pipeline time while keeping selection practical and explainable.
+Use output paths in your Playwright CLI
 
-## How It Works (High Level)
+### What you need to change
 
-1. Read changed files from Git.
-2. Mark directly changed spec files.
-3. Detect semantic impact in changed POM/utility methods.
-4. Map impacted methods to fixture usage in specs.
-5. Apply selection policy and return final spec set.
+You only need to adjust:
 
-## Before/After Example (Text)
+- `testsRootRelative`: folder where your Playwright specs live.
+- `changedSpecPrefix`: prefix used to detect directly changed specs.
+- `isRelevantPomPath`: rule for which source files are treated as POM/utility inputs.
 
-Before:
-- A change in one shared POM/utility file often leads teams to run a large suite or the full project.
+### Example output
 
-After with `test-impact-core`:
-- The same change results in a narrowed list of impacted specs only.
-- Directly changed specs are still always included.
-- CI runs faster, and failures are easier to link to the actual code change.
+Example output:
 
-## Configuration
+```text
+tests/auth/login.spec.ts
+tests/cart/cart.spec.ts
+```
 
-### Required
+If nothing is impacted:
 
-- `repoRoot`: absolute path to repository root.
-- `profile`: project configuration object.
-- `profile.testsRootRelative`: tests root relative path.
-- `profile.changedSpecPrefix`: prefix for direct changed spec detection.
-- `profile.isRelevantPomPath(filePath)`: function that returns true for relevant POM/utility files.
+```text
+No impacted specs found
+```
 
-### Optional (Advanced)
+## Minimal CI Script
 
-Most teams can skip these initially.
+Use this when your branch is compared to `origin/main`.
 
-- `analysisRootsRelative`: roots for class/method graph scan. Default: `['src/pages', 'src/utils']`.
-- `fixturesTypesRelative`: fixture map file path. Default: `src/fixtures/types.ts`.
-- `baseRef`: git ref for comparison (example: `origin/main`).
-- `includeUntrackedSpecs` (default `true`): include untracked `*.spec.ts`/`*.spec.tsx` as direct changed specs.
-- `includeWorkingTreeWithBase` (default `true`): when `baseRef` is set, union committed diff (`base...HEAD`) with current working tree diff (`HEAD`).
-- `fileExtensions` (default `['.ts', '.tsx']`): file extensions to analyze.
-- `selectionBias` (default `'fail-open'`): uncertain call-site behavior.
+```js
+const { analyzeImpactedSpecs } = require('@autotests/playwright-impact');
 
-## Result Fields (Most Used)
+const result = analyzeImpactedSpecs({
+  repoRoot: process.cwd(),
+  baseRef: 'origin/main',
+  profile: {
+    testsRootRelative: 'tests',
+    changedSpecPrefix: 'tests/',
+    isRelevantPomPath: (filePath) =>
+      (filePath.startsWith('src/pages/') || filePath.startsWith('src/utils/')) &&
+      (filePath.endsWith('.ts') || filePath.endsWith('.tsx')),
+  },
+});
 
-- `selectedSpecsRelative`: relative paths for your test runner CLI.
-- `hasAnythingToRun`: quick boolean for early exit.
-- `selectionReasons`: reason code per selected spec.
+if (!result.hasAnythingToRun) {
+  console.log('No impacted specs found');
+  process.exit(0);
+}
 
-## Advanced Diagnostics
+console.log(result.selectedSpecsRelative.join(' '));
+```
 
-- `warnings`: compatibility or uncertainty warnings.
-- `coverageStats.uncertainCallSites`: count of uncertain call sites encountered.
-- `coverageStats.statusFallbackHits`: count of git status fallbacks (`C/T/U/unknown`).
-- `changedEntriesBySource`: diagnostics for diff sources (`base...HEAD`, working tree, untracked).
+## Typical CI Usage
 
-### Reason Codes
+1. Compare current branch with `origin/main`.
+2. Compute impacted specs.
+3. Exit with `0` if nothing should run.
+4. Pass `selectedSpecsRelative` to your Playwright runner.
+
+## How It Works (High Level)
+
+1. Read changed files from Git.
+2. Include directly changed specs.
+3. Detect impacted specs from changed POM/utility code.
+4. Return a final spec list.
 
-- `direct-changed-spec`: spec was directly changed in git/untracked set.
-- `matched-precise`: spec has precise impacted fixture method usage.
-- `matched-uncertain-fail-open`: uncertain match retained by fail-open policy.
-- `retained-no-bindings`: spec kept because no fixture bindings were found in callback params.
+## Advanced Config
 
-### Selection Policy (`selectionBias`)
+Required:
+
+- `repoRoot`
+- `profile.testsRootRelative`
+- `profile.changedSpecPrefix`
+- `profile.isRelevantPomPath(filePath)`
+
+Optional:
+
+- `analysisRootsRelative`
+- `fixturesTypesRelative`
+- `baseRef`
+- `includeUntrackedSpecs`
+- `includeWorkingTreeWithBase`
+- `fileExtensions`
+- `selectionBias`
+
+## Advanced Diagnostics
 
-- Default: `fail-open` for pragmatic safety.
-- Alternative: `fail-closed` to drop uncertain matches.
+- `warnings`
+- `selectionReasons`
+- `coverageStats.uncertainCallSites`
+- `coverageStats.statusFallbackHits`
+- `changedEntriesBySource`
 
-## Notes
+## Reason Codes
 
-- This library is intentionally pragmatic and defaults to `selectionBias: 'fail-open'`.
-- For maximum safety, use `fail-open` in CI and monitor `warnings`/`uncertainCallSites`.
-- Use deterministic input (`baseRef`, clean profile predicates) for deterministic output.
+- `direct-changed-spec`
+- `matched-precise`
+- `matched-uncertain-fail-open`
+- `retained-no-bindings`

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@autotests/playwright-impact",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Core impacted-test selection library for changed POM/method analysis",
   "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akiselevaristek/playwright-impact.git"
+  },
+  "homepage": "https://github.com/akiselevaristek/playwright-impact#readme",
+  "bugs": {
+    "url": "https://github.com/akiselevaristek/playwright-impact/issues"
+  },
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js"
@@ -11,7 +19,8 @@
   "files": [
     "src",
     "tests",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"

package/tests/analyze-impacted-specs.integration.test.js

@@ -44,6 +44,34 @@ const createBaseRepo = () => {
   return dir;
 };
 
+test('README minimal profile style works with tests/ root and reports changed spec', () => {
+  const dir = createTempDir();
+  initGitRepo(dir);
+
+  writeFile(dir, 'src/pages/LoginPage.ts', 'export class LoginPage { open(){ return 1; } }\n');
+  writeFile(dir, 'src/utils/session.ts', 'export const getSession = () => "ok";\n');
+  writeFile(dir, 'src/fixtures/types.ts', 'type T = { loginPage: Pages.LoginPage };\n');
+  writeFile(dir, 'tests/auth/login.spec.ts', 'test("login", async ({ loginPage }) => { await loginPage.open(); });\n');
+  commitAll(dir, 'base');
+
+  const profile = {
+    testsRootRelative: 'tests',
+    changedSpecPrefix: 'tests/',
+    isRelevantPomPath: (filePath) =>
+      (filePath.startsWith('src/pages/') || filePath.startsWith('src/utils/')) &&
+      (filePath.endsWith('.ts') || filePath.endsWith('.tsx')),
+  };
+
+  const cleanResult = analyzeImpactedSpecs({ repoRoot: dir, profile });
+  assert.equal(cleanResult.hasAnythingToRun, false);
+
+  writeFile(dir, 'tests/auth/login.spec.ts', 'test("login", async ({ loginPage }) => { await loginPage.open(); await loginPage.open(); });\n');
+
+  const changedResult = analyzeImpactedSpecs({ repoRoot: dir, profile });
+  assert.equal(changedResult.hasAnythingToRun, true);
+  assert.equal(changedResult.selectedSpecsRelative.includes('tests/auth/login.spec.ts'), true);
+});
+
 test('analyzeImpactedSpecs returns no work when nothing changed', () => {
   const dir = createBaseRepo();
   const result = analyzeImpactedSpecs({ repoRoot: dir, profile: genericProfile, includeUntrackedSpecs: true });