@testspectra/cli 1.0.23 → 1.0.25

package/README.md

@@ -162,6 +162,7 @@ export default defineConfig({
 | Command | Description |
 | :--- | :--- |
 | `spectra init` / `npx @testspectra/cli init` | Interactive project setup. Auto-detects standalone or Nx Monorepos, discovers workspace packages from `pnpm-workspace.yaml`, and scaffolds centralized/distributed configurations. |
+| `spectra add [module]` | Adds a new TestSpectra E2E testing module to an existing workspace project or creates a new feature testing suite. |
 | `spectra run [spec]` | Automatically updates ambient declarations and invokes the native Rust test runner to execute the test suite. |
 | `spectra doctor` | Verifies local environment prerequisites (ADB, Java, Chrome, Bun, Node). |
 | `spectra devices` | Lists connected Android/iOS devices and local browsers. |

package/dist/commands/add.d.ts

@@ -0,0 +1,5 @@
+export interface AddCommandOptions {
+    e2eFolder?: string;
+    force?: boolean;
+}
+export declare function addCommand(moduleNameArg?: string, options?: AddCommandOptions): Promise<void>;

package/dist/commands/add.js

@@ -0,0 +1,372 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { TypeGenerator } from "../types/generator.js";
+function parsePnpmWorkspaceGlobs(content) {
+    const lines = content.split("\n");
+    const globs = [];
+    let inPackages = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("packages:")) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages) {
+            if (trimmed.startsWith("-")) {
+                const item = trimmed.replace(/^-\s*['"]?/, "").replace(/['"]?\s*$/, "");
+                if (item)
+                    globs.push(item);
+            }
+            else if (trimmed && !trimmed.startsWith("#")) {
+                break;
+            }
+        }
+    }
+    return globs;
+}
+function scanDirectoriesForProjects(cwd, patterns) {
+    const foundProjects = [];
+    const visited = new Set();
+    function search(dir, currentDepth, maxDepth) {
+        if (currentDepth > maxDepth || !fs.existsSync(dir))
+            return;
+        const base = path.basename(dir);
+        if (base === "node_modules" || base === "dist" || base === ".testspectra" || base === ".git" || base === "shared") {
+            return;
+        }
+        const hasPkg = fs.existsSync(path.join(dir, "package.json"));
+        const hasNx = fs.existsSync(path.join(dir, "project.json"));
+        if ((hasPkg || hasNx) && dir !== cwd) {
+            const rel = path.relative(cwd, dir);
+            if (!visited.has(rel)) {
+                visited.add(rel);
+                let name = path.basename(dir);
+                if (hasPkg) {
+                    try {
+                        const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+                        if (pkg.name)
+                            name = pkg.name;
+                    }
+                    catch { }
+                }
+                else if (hasNx) {
+                    try {
+                        const nxJson = JSON.parse(fs.readFileSync(path.join(dir, "project.json"), "utf-8"));
+                        if (nxJson.name)
+                            name = nxJson.name;
+                    }
+                    catch { }
+                }
+                foundProjects.push({
+                    name,
+                    relPath: rel,
+                    absPath: dir,
+                    hasNxProject: hasNx,
+                });
+            }
+            return;
+        }
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    search(path.join(dir, entry.name), currentDepth + 1, maxDepth);
+                }
+            }
+        }
+        catch { }
+    }
+    if (patterns.length > 0) {
+        for (const pat of patterns) {
+            const cleanPat = pat.replace(/\/\*\*?$/, "").replace(/\/\*$/, "");
+            const searchRoot = path.join(cwd, cleanPat);
+            if (fs.existsSync(searchRoot)) {
+                const stat = fs.statSync(searchRoot);
+                if (stat.isDirectory()) {
+                    search(searchRoot, 1, 3);
+                }
+            }
+        }
+    }
+    else {
+        for (const fallback of ["packages", "modules", "apps", "libs", "src"]) {
+            const fbPath = path.join(cwd, fallback);
+            if (fs.existsSync(fbPath)) {
+                search(fbPath, 1, 3);
+            }
+        }
+    }
+    return foundProjects;
+}
+export async function addCommand(moduleNameArg, options = {}) {
+    const cwd = process.cwd();
+    // 1. Locate workspace root
+    let rootDir = cwd;
+    let cur = cwd;
+    while (cur !== path.dirname(cur)) {
+        if (fs.existsSync(path.join(cur, "spectra.config.ts")) ||
+            fs.existsSync(path.join(cur, "pnpm-workspace.yaml")) ||
+            fs.existsSync(path.join(cur, "nx.json"))) {
+            rootDir = cur;
+            break;
+        }
+        cur = path.dirname(cur);
+    }
+    p.intro(chalk.bold.cyan("✨ TestSpectra Module Generator"));
+    // Check if we are in a monorepo
+    const pnpmWorkspacePath = path.join(rootDir, "pnpm-workspace.yaml");
+    const nxJsonPath = path.join(rootDir, "nx.json");
+    const isMonorepo = fs.existsSync(pnpmWorkspacePath) || fs.existsSync(nxJsonPath);
+    // 2. Resolve template directory
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    let templateDir = path.resolve(__dirname, "../templates/nx");
+    if (!fs.existsSync(templateDir)) {
+        templateDir = path.resolve(__dirname, "../../templates/nx");
+    }
+    if (!fs.existsSync(templateDir)) {
+        templateDir = path.resolve(__dirname, "../../../templates/nx");
+    }
+    const sampleE2eSrc = path.join(templateDir, "modules/auth/e2e");
+    if (!fs.existsSync(sampleE2eSrc)) {
+        p.cancel(chalk.red(`Template directory not found at: ${sampleE2eSrc}`));
+        return;
+    }
+    // 3. Resolve CLI dependency version
+    let cliVersion = "^1.0.24";
+    try {
+        const cliPackageJsonPath = path.resolve(__dirname, "../../package.json");
+        if (fs.existsSync(cliPackageJsonPath)) {
+            const cliPkg = JSON.parse(fs.readFileSync(cliPackageJsonPath, "utf-8"));
+            if (cliPkg.version) {
+                cliVersion = `^${cliPkg.version}`;
+            }
+        }
+    }
+    catch { }
+    let isInternalWorkspace = false;
+    cur = rootDir;
+    while (cur !== path.dirname(cur)) {
+        if (fs.existsSync(path.join(cur, "pnpm-workspace.yaml"))) {
+            try {
+                const wsContent = fs.readFileSync(path.join(cur, "pnpm-workspace.yaml"), "utf-8");
+                if (wsContent.includes("cli")) {
+                    isInternalWorkspace = true;
+                    break;
+                }
+            }
+            catch { }
+        }
+        cur = path.dirname(cur);
+    }
+    const cliDepVersion = isInternalWorkspace ? "workspace:*" : cliVersion;
+    function copyRecursive(src, dest, replacements = {}) {
+        const base = path.basename(src);
+        if (base === "node_modules" || base === "dist" || base === ".testspectra" || base === ".git") {
+            return;
+        }
+        const stat = fs.statSync(src);
+        if (stat.isDirectory()) {
+            if (!fs.existsSync(dest)) {
+                fs.mkdirSync(dest, { recursive: true });
+            }
+            const entries = fs.readdirSync(src);
+            for (const entry of entries) {
+                copyRecursive(path.join(src, entry), path.join(dest, entry), replacements);
+            }
+        }
+        else {
+            if (fs.existsSync(dest) && !options.force) {
+                return;
+            }
+            let content = fs.readFileSync(src, "utf-8");
+            for (const [k, v] of Object.entries(replacements)) {
+                content = content.replaceAll(k, v);
+            }
+            if (dest.endsWith("package.json")) {
+                try {
+                    const pkg = JSON.parse(content);
+                    if (pkg.devDependencies && pkg.devDependencies["@testspectra/cli"]) {
+                        pkg.devDependencies["@testspectra/cli"] = cliDepVersion;
+                    }
+                    if (pkg.dependencies && pkg.dependencies["@testspectra/cli"]) {
+                        pkg.dependencies["@testspectra/cli"] = cliDepVersion;
+                    }
+                    content = JSON.stringify(pkg, null, 2);
+                }
+                catch { }
+            }
+            fs.writeFileSync(dest, content, "utf-8");
+        }
+    }
+    // If in a Monorepo
+    if (isMonorepo) {
+        let pnpmPatterns = [];
+        if (fs.existsSync(pnpmWorkspacePath)) {
+            try {
+                pnpmPatterns = parsePnpmWorkspaceGlobs(fs.readFileSync(pnpmWorkspacePath, "utf-8"));
+            }
+            catch { }
+        }
+        const detectedProjects = scanDirectoriesForProjects(rootDir, pnpmPatterns);
+        let targetProjectPath = "";
+        let featureName = "";
+        if (moduleNameArg) {
+            // Find if moduleNameArg matches an existing detected package
+            const match = detectedProjects.find((p) => p.name === moduleNameArg || p.relPath === moduleNameArg || path.basename(p.relPath) === moduleNameArg);
+            if (match) {
+                targetProjectPath = match.relPath;
+                featureName = path.basename(match.relPath);
+            }
+            else {
+                targetProjectPath = moduleNameArg;
+                featureName = path.basename(moduleNameArg);
+            }
+        }
+        else {
+            const mode = await p.select({
+                message: "How would you like to add the TestSpectra module?",
+                options: [
+                    {
+                        label: "Add E2E to an existing workspace project / feature",
+                        value: "existing",
+                        hint: "Attach E2E test suite to a detected workspace package",
+                    },
+                    {
+                        label: "Create a new custom feature / module path",
+                        value: "custom",
+                        hint: "Specify a custom path e.g. packages/features/billing",
+                    },
+                ],
+            });
+            if (p.isCancel(mode)) {
+                p.cancel("Operation cancelled.");
+                return;
+            }
+            if (mode === "existing" && detectedProjects.length > 0) {
+                const choice = await p.select({
+                    message: "Select workspace project to add TestSpectra E2E testing to:",
+                    options: detectedProjects.map((proj) => ({
+                        value: proj.relPath,
+                        label: `${proj.relPath} (${proj.name})`,
+                        hint: proj.hasNxProject ? "Nx project.json" : "package.json",
+                    })),
+                });
+                if (p.isCancel(choice)) {
+                    p.cancel("Operation cancelled.");
+                    return;
+                }
+                targetProjectPath = choice;
+                featureName = path.basename(targetProjectPath);
+            }
+            else {
+                const customPath = await p.text({
+                    message: "Enter path for the new feature module (e.g. packages/features/payment):",
+                    placeholder: "packages/features/new-feature",
+                    validate: (val) => {
+                        if (!val || !val.trim())
+                            return "Path cannot be empty";
+                    },
+                });
+                if (p.isCancel(customPath)) {
+                    p.cancel("Operation cancelled.");
+                    return;
+                }
+                targetProjectPath = customPath.trim();
+                featureName = path.basename(targetProjectPath);
+            }
+        }
+        const e2eFolderName = options.e2eFolder || "e2e";
+        const targetE2eDir = path.join(rootDir, targetProjectPath, e2eFolderName);
+        const e2eProjectName = `${featureName}-${e2eFolderName}`;
+        if (fs.existsSync(targetE2eDir) && !options.force) {
+            p.log.warn(chalk.yellow(`E2E module already exists at ./${path.relative(rootDir, targetE2eDir)}. Use --force to overwrite.`));
+            return;
+        }
+        const s = p.spinner();
+        s.start(`Scaffolding ${e2eProjectName} in ./${path.relative(rootDir, targetE2eDir)}...`);
+        copyRecursive(sampleE2eSrc, targetE2eDir, {
+            "auth-e2e": e2eProjectName,
+            "modules/auth/e2e": path.relative(rootDir, targetE2eDir).replace(/\\/g, "/"),
+            "scope:auth": `scope:${featureName}`,
+        });
+        // Adjust project.json
+        const projJsonPath = path.join(targetE2eDir, "project.json");
+        if (fs.existsSync(projJsonPath)) {
+            try {
+                const pObj = JSON.parse(fs.readFileSync(projJsonPath, "utf-8"));
+                pObj.name = e2eProjectName;
+                pObj.sourceRoot = path.relative(rootDir, targetE2eDir).replace(/\\/g, "/");
+                pObj.targets.e2e.options.cwd = path.relative(rootDir, targetE2eDir).replace(/\\/g, "/");
+                pObj.targets["type-check"].options.cwd = path.relative(rootDir, targetE2eDir).replace(/\\/g, "/");
+                pObj.tags = [`scope:${featureName}`, "type:e2e"];
+                fs.writeFileSync(projJsonPath, JSON.stringify(pObj, null, 2), "utf-8");
+            }
+            catch { }
+        }
+        // Ensure no local spectra.config.ts (centralized in root)
+        const localConfig = path.join(targetE2eDir, "spectra.config.ts");
+        if (fs.existsSync(localConfig))
+            fs.unlinkSync(localConfig);
+        // Update Root Solution tsconfig.json references
+        const rootTsConfigPath = path.join(rootDir, "tsconfig.json");
+        if (fs.existsSync(rootTsConfigPath)) {
+            try {
+                const rootTsConfig = JSON.parse(fs.readFileSync(rootTsConfigPath, "utf-8"));
+                if (!rootTsConfig.references)
+                    rootTsConfig.references = [];
+                const relRef = `./${path.relative(rootDir, targetE2eDir).replace(/\\/g, "/")}`;
+                if (!rootTsConfig.references.some((r) => r.path === relRef)) {
+                    rootTsConfig.references.push({ path: relRef });
+                    fs.writeFileSync(rootTsConfigPath, JSON.stringify(rootTsConfig, null, 2), "utf-8");
+                }
+            }
+            catch { }
+        }
+        // Generate Ambient Types for root and new module
+        TypeGenerator.writeDeclarationFiles(rootDir);
+        TypeGenerator.writeDeclarationFiles(targetE2eDir);
+        s.stop(`Module ${e2eProjectName} added successfully!`);
+        p.log.success(chalk.green(`Directory: ./${path.relative(rootDir, targetE2eDir)}`));
+        p.log.success(chalk.green(`Nx Target: ${e2eProjectName}:e2e`));
+        p.log.message(chalk.cyan(`Run tests: pnpm nx run ${e2eProjectName}:e2e`));
+        p.outro(chalk.bold.green("🎉 New TestSpectra module ready!"));
+        return;
+    }
+    // Standalone mode: adding a new spec suite in specs/<ModuleName>
+    let targetModule = moduleNameArg;
+    if (!targetModule) {
+        const input = await p.text({
+            message: "Enter name of the new test suite/module (e.g. Payment, Profile):",
+            placeholder: "Checkout",
+            validate: (val) => {
+                if (!val || !val.trim())
+                    return "Module name cannot be empty";
+            },
+        });
+        if (p.isCancel(input)) {
+            p.cancel("Operation cancelled.");
+            return;
+        }
+        targetModule = input.trim();
+    }
+    const specDir = path.join(cwd, "specs", targetModule, "TC-01");
+    const poDir = path.join(cwd, "page-objects", `${targetModule}Page`);
+    if (!fs.existsSync(specDir))
+        fs.mkdirSync(specDir, { recursive: true });
+    if (!fs.existsSync(poDir))
+        fs.mkdirSync(poDir, { recursive: true });
+    // Create starter page object
+    const poContent = `class ${targetModule}Page {\n  get mainTitle() {\n    return $("h1");\n  }\n\n  async open() {\n    await Spectra.navigate("/${targetModule.toLowerCase()}");\n  }\n}\n\nexport default new ${targetModule}Page();\n`;
+    fs.writeFileSync(path.join(poDir, "common.ts"), poContent, "utf-8");
+    // Create starter test spec
+    const specContent = `describe("${targetModule} Test Suite", () => {\n  it("should verify ${targetModule} page components", async () => {\n    await ${targetModule}Page.open();\n    await ${targetModule}Page.mainTitle.shouldBeVisible();\n  });\n});\n`;
+    fs.writeFileSync(path.join(specDir, "web.test.ts"), specContent, "utf-8");
+    TypeGenerator.writeDeclarationFiles(cwd);
+    p.log.success(chalk.green(`Created Page Object: ./page-objects/${targetModule}Page/common.ts`));
+    p.log.success(chalk.green(`Created Test Spec: ./specs/${targetModule}/TC-01/web.test.ts`));
+    p.outro(chalk.bold.green(`🎉 Suite ${targetModule} added successfully!`));
+}

package/dist/commands/init.js

@@ -382,12 +382,9 @@ export async function initCommand(options = {}) {
                 fs.unlinkSync(localConfig);
             featureE2eDirs.push(targetE2eDir);
         }
-        // 5. Ensure pnpm-workspace.yaml includes shared library and all feature E2E directories
+        // 5. Ensure pnpm-workspace.yaml includes shared library (feature modules are already part of existing workspace globs)
         const pnpmWorkspaceFilePath = path.join(cwd, "pnpm-workspace.yaml");
         ensurePnpmWorkspaceIncludes(pnpmWorkspaceFilePath, sharedTestingRelPath);
-        for (const e2eDir of featureE2eDirs) {
-            ensurePnpmWorkspaceIncludes(pnpmWorkspaceFilePath, path.relative(cwd, e2eDir));
-        }
         // 6. Update Root Solution tsconfig.json references
         const rootTsConfigPath = path.join(cwd, "tsconfig.json");
         const references = [];

package/dist/index.js

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { addCommand } from "./commands/add.js";
 import { devicesCommand } from "./commands/devices.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { initCommand } from "./commands/init.js";
@@ -20,6 +21,12 @@ export function createCliProgram() {
         .option("-t, --template <template>", "Project template: default, nx")
         .option("-f, --force", "Overwrite existing configuration if present")
         .action(initCommand);
+    program
+        .command("add [module]")
+        .description("Add a new TestSpectra E2E testing module to workspace or standalone project")
+        .option("-e, --e2e-folder <name>", "Name of E2E sub-folder (default: e2e)")
+        .option("-f, --force", "Overwrite existing module files if present")
+        .action(addCommand);
     program
         .command("doctor")
         .description("Verify local environment prerequisites (ADB, Java, Chrome, Bun, Node)")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",