@testspectra/cli 1.1.7 → 1.1.8-rc.1

package/dist/linter/__tests__/step-parity.test.js

@@ -0,0 +1,372 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SpecLinter } from '../spec-linter.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+describe('Step Parity & Symbol Integrity Linter (Stage 3 & Stage 4)', () => {
+    const tempDir = path.join(__dirname, '__temp_parity__');
+    beforeEach(() => {
+        fs.mkdirSync(tempDir, { recursive: true });
+    });
+    afterEach(() => {
+        if (fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    it('passes validation when declared @step directives match Step.*() invocations in web.test.ts', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0100-matching
+title: Valid login step matching
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Valid login step matching
+
+## Test Steps
+1. @step:login
+2. Assert dashboard loaded
+`);
+        fs.writeFileSync(testPath, `it("Valid login step matching", async () => {
+  await Step.login();
+  await LoginPage.submitButton.should("be.visible");
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        expect(result.diagnostics).toHaveLength(0);
+    });
+    it('emits testspectra/missing-step-call when a declared @step is absent in web.test.ts', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0101-missing-in-code
+title: Step declared but missing in code
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Step declared but missing in code
+
+## Test Steps
+1. @step:login
+2. @step:logout
+`);
+        fs.writeFileSync(testPath, `it("Step declared but missing in code", async () => {
+  await Step.login();
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const missingErrors = result.diagnostics.filter((d) => d.code === 'testspectra/missing-step-call');
+        expect(missingErrors).toHaveLength(1);
+        expect(missingErrors[0].severity).toBe('error');
+        expect(missingErrors[0].message).toContain('Step "@step:logout" declared in spec.md line 15 is missing in web.test.ts');
+        expect(missingErrors[0].line).toBe(15);
+    });
+    it('emits testspectra/undocumented-step warning when Step.*() called in test script is not documented in spec.md', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0102-undocumented-step
+title: Undocumented step call
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Undocumented step call
+
+## Test Steps
+1. @step:login
+`);
+        fs.writeFileSync(testPath, `it("Undocumented step call", async () => {
+  await Step.login();
+  await Step.logout();
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const warnings = result.diagnostics.filter((d) => d.code === 'testspectra/undocumented-step');
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0].severity).toBe('warning');
+        expect(warnings[0].message).toContain('Step "logout" called in web.test.ts:L3 is not documented with @step:logout in spec.md');
+        expect(warnings[0].line).toBe(3);
+    });
+    it('emits testspectra/title-mismatch warning when it() title in test script differs from spec.md title', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0103-title-mismatch
+title: Verify user profile updates
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Verify user profile updates
+
+## Test Steps
+1. Open profile and change name
+`);
+        fs.writeFileSync(testPath, `it("should process checkout cart items", async () => {
+  await CartPage.checkout();
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const titleWarnings = result.diagnostics.filter((d) => d.code === 'testspectra/title-mismatch');
+        expect(titleWarnings).toHaveLength(1);
+        expect(titleWarnings[0].severity).toBe('warning');
+        expect(titleWarnings[0].message).toContain('Test title "should process checkout cart items" in web.test.ts:L1 does not match spec.md title "Verify user profile updates"');
+    });
+    it('does not emit testspectra/title-mismatch warning when it() title is directly aligned with spec.md title', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0104-title-aligned
+title: Verify playground form inputs and default states
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Verify playground form inputs and default states
+
+## Test Steps
+1. Check form inputs
+`);
+        fs.writeFileSync(testPath, `it("Verify playground form inputs and default states", async () => {
+  await PlaygroundPage.open();
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const titleWarnings = result.diagnostics.filter((d) => d.code === 'testspectra/title-mismatch');
+        expect(titleWarnings).toHaveLength(0);
+    });
+    it('emits testspectra/no-manual-import error when manual import statements are detected in test script', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0105-manual-imports
+title: Forbidden manual imports
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Forbidden manual imports
+
+## Test Steps
+1. Test without manual imports
+`);
+        fs.writeFileSync(testPath, `import { expect } from 'vitest';
+import path from 'path';
+
+it("Forbidden manual imports", async () => {
+  expect(1).toBe(1);
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const importErrors = result.diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
+        expect(importErrors).toHaveLength(2);
+        expect(importErrors[0].severity).toBe('error');
+        expect(importErrors[0].message).toContain('Manual imports forbidden');
+        expect(importErrors[0].line).toBe(1);
+        expect(importErrors[1].line).toBe(2);
+    });
+    it('emits testspectra/single-it-required error when test script contains 0 it() blocks', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0106-zero-it
+title: Zero it blocks test
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Zero it blocks test
+
+## Test Steps
+1. Execute step
+`);
+        fs.writeFileSync(testPath, `// Helper file with no test execution block
+const dummy = 123;
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const itErrors = result.diagnostics.filter((d) => d.code === 'testspectra/single-it-required');
+        expect(itErrors).toHaveLength(1);
+        expect(itErrors[0].severity).toBe('error');
+        expect(itErrors[0].message).toContain('Test case script must contain exactly one it() block (found 0)');
+    });
+    it('emits testspectra/single-it-required error when test script contains multiple it() blocks', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0107-multiple-it
+title: Multiple it blocks test
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Multiple it blocks test
+
+## Test Steps
+1. First step
+2. Second step
+`);
+        fs.writeFileSync(testPath, `it("Multiple it blocks test", async () => {
+  await Step.first();
+});
+
+it("should execute second step", async () => {
+  await Step.second();
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const itErrors = result.diagnostics.filter((d) => d.code === 'testspectra/single-it-required');
+        expect(itErrors).toHaveLength(1);
+        expect(itErrors[0].severity).toBe('error');
+        expect(itErrors[0].message).toContain('Multiple it() blocks detected (2); each test script must contain exactly one it() block');
+        expect(itErrors[0].line).toBe(5);
+    });
+    it('emits testspectra/no-test-block error when test() block is used instead of it()', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0108-test-keyword
+title: Test keyword forbidden
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Test keyword forbidden
+
+## Test Steps
+1. Execute step
+`);
+        fs.writeFileSync(testPath, `test("Test keyword forbidden", async () => {
+  await Step.first();
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const testErrors = result.diagnostics.filter((d) => d.code === 'testspectra/no-test-block');
+        expect(testErrors).toHaveLength(1);
+        expect(testErrors[0].severity).toBe('error');
+        expect(testErrors[0].message).toContain('test() is forbidden; TestSpectra test scripts must strictly use it() instead of test()');
+        expect(testErrors[0].line).toBe(1);
+    });
+    it('emits testspectra/no-describe-block error when describe() block is detected in test script', () => {
+        const specPath = path.join(tempDir, 'spec.md');
+        const testPath = path.join(tempDir, 'web.test.ts');
+        fs.writeFileSync(specPath, `---
+id: TC-0108-describe-block
+title: Describe block forbidden
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Describe block forbidden
+
+## Test Steps
+1. Execute test inside describe
+`);
+        fs.writeFileSync(testPath, `describe("Describe block forbidden suite", () => {
+  it("Describe block forbidden", async () => {
+    await LoginPage.open();
+  });
+});
+`);
+        const result = SpecLinter.validateSpecFile(specPath);
+        const descErrors = result.diagnostics.filter((d) => d.code === 'testspectra/no-describe-block');
+        expect(descErrors).toHaveLength(1);
+        expect(descErrors[0].severity).toBe('error');
+        expect(descErrors[0].message).toContain('describe() blocks are forbidden; test suites are structured via directory hierarchy with suite.md');
+        expect(descErrors[0].line).toBe(1);
+    });
+    describe('testspectra/no-manual-import extended to non-test scripts', () => {
+        it('emits testspectra/no-manual-import when shared step file contains import statements', () => {
+            const stepsDir = path.join(tempDir, 'shared', 'testing', 'support', 'steps', 'login');
+            fs.mkdirSync(stepsDir, { recursive: true });
+            fs.writeFileSync(path.join(stepsDir, 'web.step.ts'), `import { expect } from 'vitest';
+import path from 'path';
+
+export default async function login() {
+  await LoginPage.open();
+}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const importErrors = result.diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
+            expect(importErrors).toHaveLength(2);
+            expect(importErrors[0].severity).toBe('error');
+            expect(importErrors[0].message).toContain('Manual imports forbidden');
+            expect(importErrors[0].filePath).toContain('web.step.ts');
+        });
+        it('emits testspectra/no-manual-import when shared action file contains import statements', () => {
+            const actionsDir = path.join(tempDir, 'shared', 'testing', 'support', 'actions', 'fillForm');
+            fs.mkdirSync(actionsDir, { recursive: true });
+            fs.writeFileSync(path.join(actionsDir, 'web.action.ts'), `import { Page } from 'playwright';
+
+export default async function (email: string) {
+  await this.get("#email").type(email);
+}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const importErrors = result.diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
+            expect(importErrors).toHaveLength(1);
+            expect(importErrors[0].filePath).toContain('web.action.ts');
+        });
+        it('emits testspectra/no-manual-import when shared hook file contains import statements', () => {
+            const hooksDir = path.join(tempDir, 'shared', 'testing', 'global-hooks', 'before');
+            fs.mkdirSync(hooksDir, { recursive: true });
+            fs.writeFileSync(path.join(hooksDir, 'web.hook.ts'), `import { database } from './setup';
+
+export default async function () {
+  await database.reset();
+}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const importErrors = result.diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
+            expect(importErrors).toHaveLength(1);
+            expect(importErrors[0].filePath).toContain('web.hook.ts');
+        });
+        it('does NOT emit testspectra/no-manual-import when shared step has no imports', () => {
+            const stepsDir = path.join(tempDir, 'shared', 'testing', 'support', 'steps', 'verify');
+            fs.mkdirSync(stepsDir, { recursive: true });
+            fs.writeFileSync(path.join(stepsDir, 'web.step.ts'), `export default async function verifyState() {
+  await Page.open();
+  await Page.element.should("be.visible");
+}
+`);
+            const result = SpecLinter.validateWorkspace(tempDir);
+            const importErrors = result.diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
+            expect(importErrors).toHaveLength(0);
+        });
+    });
+});

package/dist/linter/discovery.d.ts

@@ -0,0 +1,30 @@
+export interface WorkspaceAssets {
+    sharedSteps: Set<string>;
+    pageObjects: Set<string>;
+    fixtures: Set<string>;
+}
+/**
+ * Scans a workspace directory for all `project.json` files that have both
+ * "scope:shared" and "type:shared" tags, and returns their parent folder paths.
+ */
+export declare function findSharedLibraryRoots(workspaceDir: string): string[];
+/**
+ * Resolves the root directory of a shared testing library if the file path is inside one.
+ * Determines shared library status based on `project.json` containing
+ * both "scope:shared" and "type:shared" tags in ancestor directories,
+ * taking the parent folder of that `project.json` as the shared library root.
+ */
+export declare function getSharedLibraryRoot(filePath: string, workspaceDir?: string): string | null;
+/**
+ * Checks if a file path is inside a shared testing library directory.
+ */
+export declare function isInsideSharedLibrary(filePath: string, workspaceDir?: string): boolean;
+/**
+ * Traverses upwards to locate the project root containing spectra.config.ts or package.json.
+ */
+export declare function findProjectRoot(startDir: string): string;
+/**
+ * Discovers and indexes all available shared steps, page objects, and fixtures
+ * across the workspace (including root and shared directories).
+ */
+export declare function discoverWorkspaceAssets(workspaceDir: string): WorkspaceAssets;

package/dist/linter/discovery.js

@@ -0,0 +1,249 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Scans a workspace directory for all `project.json` files that have both
+ * "scope:shared" and "type:shared" tags, and returns their parent folder paths.
+ */
+export function findSharedLibraryRoots(workspaceDir) {
+    const sharedRoots = [];
+    const ignoredDirs = new Set(['node_modules', 'dist', '.git', '.testspectra', 'build', 'coverage']);
+    const scan = (dir) => {
+        if (!fs.existsSync(dir))
+            return;
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    if (ignoredDirs.has(entry.name))
+                        continue;
+                    scan(path.join(dir, entry.name));
+                }
+                else if (entry.isFile() && entry.name === 'project.json') {
+                    try {
+                        const raw = fs.readFileSync(path.join(dir, entry.name), 'utf-8');
+                        const parsed = JSON.parse(raw);
+                        const tags = Array.isArray(parsed.tags) ? parsed.tags : [];
+                        if (tags.includes('scope:shared') && tags.includes('type:shared')) {
+                            sharedRoots.push(dir);
+                        }
+                    }
+                    catch { }
+                }
+            }
+        }
+        catch { }
+    };
+    scan(workspaceDir);
+    return sharedRoots;
+}
+/**
+ * Resolves the root directory of a shared testing library if the file path is inside one.
+ * Determines shared library status based on `project.json` containing
+ * both "scope:shared" and "type:shared" tags in ancestor directories,
+ * taking the parent folder of that `project.json` as the shared library root.
+ */
+export function getSharedLibraryRoot(filePath, workspaceDir) {
+    const resolved = workspaceDir && !path.isAbsolute(filePath) ? path.resolve(workspaceDir, filePath) : path.resolve(filePath);
+    let current = resolved;
+    try {
+        if (fs.existsSync(current)) {
+            if (fs.statSync(current).isFile()) {
+                current = path.dirname(current);
+            }
+        }
+        else if (path.extname(current)) {
+            current = path.dirname(current);
+        }
+    }
+    catch {
+        if (path.extname(current)) {
+            current = path.dirname(current);
+        }
+    }
+    while (true) {
+        const projectJsonPath = path.join(current, 'project.json');
+        if (fs.existsSync(projectJsonPath)) {
+            try {
+                const raw = fs.readFileSync(projectJsonPath, 'utf-8');
+                const projectConfig = JSON.parse(raw);
+                const tags = Array.isArray(projectConfig.tags) ? projectConfig.tags : [];
+                if (tags.includes('scope:shared') && tags.includes('type:shared')) {
+                    return current;
+                }
+                return null;
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Checks if a file path is inside a shared testing library directory.
+ */
+export function isInsideSharedLibrary(filePath, workspaceDir) {
+    return getSharedLibraryRoot(filePath, workspaceDir) !== null;
+}
+/**
+ * Traverses upwards to locate the project root containing spectra.config.ts or package.json.
+ */
+export function findProjectRoot(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        if (fs.existsSync(path.join(current, 'spectra.config.ts')) ||
+            fs.existsSync(path.join(current, 'spectra.config.js'))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    // Fallback: search for package.json
+    current = path.resolve(startDir);
+    while (true) {
+        if (fs.existsSync(path.join(current, 'package.json'))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return startDir;
+}
+/**
+ * Discovers and indexes all available shared steps, page objects, and fixtures
+ * across the workspace (including root and shared directories).
+ */
+export function discoverWorkspaceAssets(workspaceDir) {
+    const assets = {
+        sharedSteps: new Set(),
+        pageObjects: new Set(),
+        fixtures: new Set(),
+    };
+    const candidateRoots = [
+        workspaceDir,
+        ...findSharedLibraryRoots(workspaceDir),
+        path.join(workspaceDir, 'shared', 'testing'),
+        path.join(workspaceDir, 'shared'),
+        path.join(workspaceDir, 'testing'),
+    ];
+    // Also check packages in monorepos if packages/ directory exists
+    const packagesDir = path.join(workspaceDir, 'packages');
+    if (fs.existsSync(packagesDir)) {
+        try {
+            const pkgs = fs.readdirSync(packagesDir, { withFileTypes: true });
+            for (const pkg of pkgs) {
+                if (pkg.isDirectory()) {
+                    candidateRoots.push(path.join(packagesDir, pkg.name));
+                    candidateRoots.push(path.join(packagesDir, pkg.name, 'e2e'));
+                }
+            }
+        }
+        catch { }
+    }
+    const scanFileForPageClasses = (filePath) => {
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const matches = content.matchAll(/(?:class|interface)\s+([A-Za-z0-9_]+Page)\b/g);
+            for (const match of matches) {
+                assets.pageObjects.add(match[1]);
+            }
+        }
+        catch { }
+    };
+    for (const root of candidateRoots) {
+        if (!fs.existsSync(root))
+            continue;
+        // 1. Shared Steps (support/steps or steps)
+        const stepDirs = [path.join(root, 'support', 'steps'), path.join(root, 'steps')];
+        for (const sDir of stepDirs) {
+            if (fs.existsSync(sDir) && fs.statSync(sDir).isDirectory()) {
+                try {
+                    const entries = fs.readdirSync(sDir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        if (entry.isDirectory()) {
+                            assets.sharedSteps.add(entry.name);
+                        }
+                        else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.js'))) {
+                            const nameWithoutExt = path.basename(entry.name, path.extname(entry.name));
+                            if (nameWithoutExt !== 'index') {
+                                assets.sharedSteps.add(nameWithoutExt);
+                            }
+                        }
+                    }
+                }
+                catch { }
+            }
+        }
+        // 2. Page Objects (page-objects or pageobjects)
+        const poDirs = [path.join(root, 'page-objects'), path.join(root, 'pageobjects')];
+        for (const poDir of poDirs) {
+            if (fs.existsSync(poDir) && fs.statSync(poDir).isDirectory()) {
+                try {
+                    const entries = fs.readdirSync(poDir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        if (entry.isDirectory()) {
+                            assets.pageObjects.add(entry.name);
+                            // Also inspect files in the subdirectory
+                            try {
+                                const subEntries = fs.readdirSync(path.join(poDir, entry.name), { withFileTypes: true });
+                                for (const sub of subEntries) {
+                                    if (sub.isFile() && (sub.name.endsWith('.ts') || sub.name.endsWith('.js'))) {
+                                        scanFileForPageClasses(path.join(poDir, entry.name, sub.name));
+                                    }
+                                }
+                            }
+                            catch { }
+                        }
+                        else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.js'))) {
+                            const nameWithoutExt = path.basename(entry.name, path.extname(entry.name));
+                            if (nameWithoutExt !== 'index') {
+                                assets.pageObjects.add(nameWithoutExt);
+                            }
+                            scanFileForPageClasses(path.join(poDir, entry.name));
+                        }
+                    }
+                }
+                catch { }
+            }
+        }
+        // 3. Fixtures (fixtures)
+        const fixDir = path.join(root, 'fixtures');
+        if (fs.existsSync(fixDir) && fs.statSync(fixDir).isDirectory()) {
+            try {
+                const entries = fs.readdirSync(fixDir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isFile()) {
+                        const nameWithoutExt = path.basename(entry.name, path.extname(entry.name));
+                        assets.fixtures.add(nameWithoutExt);
+                    }
+                    else if (entry.isDirectory()) {
+                        assets.fixtures.add(entry.name);
+                        try {
+                            const subEntries = fs.readdirSync(path.join(fixDir, entry.name), { withFileTypes: true });
+                            for (const sub of subEntries) {
+                                if (sub.isFile()) {
+                                    const subNameWithoutExt = path.basename(sub.name, path.extname(sub.name));
+                                    assets.fixtures.add(subNameWithoutExt);
+                                }
+                            }
+                        }
+                        catch { }
+                    }
+                }
+            }
+            catch { }
+        }
+    }
+    return assets;
+}