@testspectra/cli 1.0.18 → 1.0.20

package/README.md

@@ -161,14 +161,14 @@ export default defineConfig({
 
 | Command | Description |
 | :--- | :--- |
-| `spectra init` | Scaffolds a complete multi-platform project from scratch with tsconfigs, specs, page objects, actions, steps, and fixtures. |
-| `spectra run` | Generates declaration types and invokes the native Rust test runner to execute the test suite. |
+| `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 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. |
 
 ---
 
-## 4. Directory Structure of a TestSpectra Project
+## 4. Standalone Project Directory Structure
 
 ```
 ├── spectra.config.ts            # Central typed project configuration
@@ -189,19 +189,17 @@ export default defineConfig({
 │   └── loginUser/
 │         ├── web.step.ts
 │         └── mobile.step.ts
-├── hooks/                       # Suite lifecycle hooks
-│   └── default/
-│         ├── before.web.hook.ts
-│         ├── before.android.hook.ts
-│         └── before.ios.hook.ts
-├── specs/                       # Standalone zero-import test cases
-│   └── TC-LOGIN-01/
-│         ├── web.test.ts
-│         ├── android.test.ts
-│         └── ios.test.ts
+├── global-hooks/                # Global lifecycle hooks
+│   └── before.web.hook.ts
+├── specs/                       # Layered zero-import test cases
+│   └── Auth/
+│         └── TC-AUTH-01/
+│               ├── web.test.ts
+│               ├── android.test.ts
+│               └── ios.test.ts
 ├── fixtures/                    # Platform-agnostic test data
 │   └── userData.json
-└── .testspectra/                # Auto-generated ambient typings
+└── .testspectra/                # Auto-generated ambient typings & cache
     └── types/
           ├── fixtures.d.ts
           ├── web.d.ts
@@ -213,15 +211,83 @@ export default defineConfig({
 
 ---
 
-## 5. Development & Verification
+## 5. Enterprise Monorepo Architecture (Nx & PNPM Workspace)
+
+TestSpectra features an enterprise-grade architecture for large monorepos: **"Centralized Configuration, Distributed Implementation"**.
+
+```
+                  ┌───────────────────────────────────────────────────────────┐
+                  │                 Root Monorepo Directory                   │
+                  │                                                           │
+                  │  ├── spectra.config.ts       (Central Execution Config)   │
+                  │  ├── .testspectra/           (Central Cache, AppData, Log)│
+                  │  ├── pnpm-workspace.yaml     (Workspace Definition)       │
+                  │  ├── nx.json                 (Nx Target & Caching Rules)  │
+                  │  └── tsconfig.json           (Solution References)        │
+                  └─────────────────────────────┬─────────────────────────────┘
+                                                │
+                 ┌──────────────────────────────┴──────────────────────────────┐
+                 ▼                                                             ▼
+  ┌───────────────────────────────┐                             ┌───────────────────────────────┐
+  │   shared/testing/ (Library)   │                             │  packages/features/auth/e2e/  │
+  ├───────────────────────────────┤                             ├───────────────────────────────┤
+  │ - Shared Page Objects         │ ◄─── Auto-Scanned Globals ──│ - Feature Specs (specs/)      │
+  │ - Shared Steps (loginAsAdmin) │     (100% Zero-Import!)     │ - Feature Page Objects (POMs) │
+  │ - Shared Actions (dismissBtn) │                             │ - project.json (Nx Target)    │
+  │ - Shared Fixtures (appConfig) │                             │ - tsconfig.web/android/ios    │
+  └───────────────────────────────┘                             └───────────────────────────────┘
+```
+
+### Key Pillars of Monorepo Integration:
+
+1. **Interactive Workspace Auto-Discovery (`spectra init`)**:
+   - Parses `pnpm-workspace.yaml` (e.g. `packages/features/*`, `modules/**`).
+   - Scans sub-directories for existing `project.json` or `package.json`.
+   - Prompts the user with an interactive multi-select checkbox to choose which features will receive E2E testing.
+   - Prompts for customizable E2E folder names (e.g. `e2e`, `test/e2e`) and the shared testing library path (`shared/testing`).
+
+2. **Centralized Configuration (`spectra.config.ts`) & App Data (`.testspectra/`)**:
+   - `spectra.config.ts` lives exclusively at the root of the monorepo.
+   - CLI test runs executed from sub-feature folders automatically traverse up to find the root configuration.
+   - Driver caches, binaries, and logs reside in `<root>/.testspectra/`, preventing repository clutter across individual feature folders.
+
+3. **Global Zero-Import Consumption of Shared Library**:
+   - Entities placed inside `shared/testing/page-objects/`, `shared/testing/steps/`, `shared/testing/actions/`, and `shared/testing/fixtures/` are automatically aggregated into ambient declarations.
+   - Feature test specs consume shared Page Objects (`NavigationBar.goToHome()`), steps (`Step.loginAsAdmin()`), actions (`Spectra.dismissBanner()`), and fixtures (`Fixture.appConfig`) **without a single line of `import` statement**.
+
+4. **Nx Target Execution & Affected Caching**:
+   - Each feature E2E folder includes an Nx `project.json`:
+     ```json
+     {
+       "name": "auth-e2e",
+       "targets": {
+         "e2e": {
+           "executor": "nx:run-commands",
+           "options": { "command": "spectra run", "cwd": "modules/auth/e2e" },
+           "configurations": {
+             "android": { "command": "spectra run --target android" },
+             "ios": { "command": "spectra run --target ios" },
+             "headless": { "command": "spectra run --headless" }
+           }
+         }
+       }
+     }
+     ```
+   - Running `nx run-many -t e2e` executes all feature test suites in parallel.
+5. **Automatic Architecture Documentation (`ARCHITECTURE.md`)**:
+   - Every `spectra init` run produces a comprehensive, project-tailored `ARCHITECTURE.md` file in the root workspace.
+   - It documents the generated file map, exact distributed feature paths, shared library resolution, and zero-import mechanics for onboarding engineers.
+
+---
+
+## 6. Development & Verification
 
 To verify the CLI and example app:
 ```bash
 # Build CLI
 pnpm --filter @testspectra/cli build
 
-# Initialize and verify example app
-cd apps/example-app
-../../cli/bin/spectra.js init
-npx tsc -b tsconfig.json
+# Test interactive scaffolding
+npx @testspectra/cli init
+pnpm type-check
 ```

package/dist/commands/init.js

@@ -190,6 +190,7 @@ export async function initCommand(options = {}) {
         }
         cur = path.dirname(cur);
     }
+    const projectName = path.basename(cwd);
     const cliDepVersion = isInternalWorkspace ? "workspace:*" : cliVersion;
     // Helper: Copy directory contents recursively
     function copyRecursive(src, dest, replacements = {}) {
@@ -343,21 +344,102 @@ export async function initCommand(options = {}) {
         else {
             rootTsConfig = { files: [], references };
         }
-        fs.writeFileSync(rootTsConfigPath, JSON.stringify(rootTsConfig, null, 2), "utf-8");
         // 6. Generate Ambient Types for Shared + All E2E Feature Directories
         TypeGenerator.writeDeclarationFiles(cwd);
         for (const e2eDir of featureE2eDirs) {
             TypeGenerator.writeDeclarationFiles(e2eDir);
         }
+        // 7. Generate ARCHITECTURE.md in root documenting the exact generated layout
+        const archDocContent = `# TestSpectra Enterprise Monorepo Architecture
+
+This workspace uses TestSpectra's **"Centralized Configuration, Distributed Implementation"** model for automated cross-platform testing.
+
+---
+
+## 1. Directory & File Overview
+
+### Centralized Root Elements
+- \`./spectra.config.ts\`: Single source of truth for runtime configurations (Base URL, Appium devices, browser targets, timeouts).
+- \`./.testspectra/\`: Centralized app data folder containing driver caches (ChromeDriver, GeckoDriver, Appium), execution logs, and universal ambient types (\`.testspectra/types/\`).
+- \`./nx.json\`: Nx target defaults with execution caching and inputs.
+- \`./pnpm-workspace.yaml\`: Monorepo package glob definitions.
+- \`./tsconfig.json\`: Solution-style TypeScript orchestrator linking all distributed E2E projects and shared libraries.
+
+### Centralized Shared Library (\`./${sharedTestingRelPath}\`)
+Provides cross-feature reusable test entities with **100% zero-import global resolution**:
+- \`page-objects/\`: Shared Page Object models (e.g. NavigationBar, AppHeader).
+- \`steps/\`: Cross-feature business step flows (e.g. \`Step.loginAsAdmin()\`).
+- \`actions/\`: Custom atomic actions (e.g. \`Spectra.dismissBanner()\`).
+- \`fixtures/\`: Common test data and environment configurations (e.g. \`Fixture.appConfig\`).
+
+### Distributed Feature E2E Modules (${featureE2eDirs.length} Features)
+${featureE2eDirs.map((d) => {
+            const rel = path.relative(cwd, d);
+            const name = path.basename(path.dirname(d));
+            return `- \`./${rel}\` (**${name}**):
+  - \`specs/\`: Feature test cases (\`specs/<SuiteName>/<CaseId>/\` for web, android, ios).
+  - \`page-objects/\`: Feature-specific Page Objects (e.g. LoginPage, ProductPage).
+  - \`project.json\`: Nx targets (\`e2e\`, \`type-check\`) supporting configurations (\`--configuration=android\`, \`--configuration=ios\`, \`--configuration=headless\`).
+  - \`tsconfig.json\`: Solution TypeScript config reference.`;
+        }).join("\n")}
+
+---
+
+## 2. Zero-Import Consumption Flow
+
+\`\`\`
+  ┌──────────────────────────────┐          ┌──────────────────────────────┐
+  │ shared/testing/page-objects  │          │   modules/*/e2e/specs/       │
+  │ shared/testing/steps         │ ───────► │   (Zero-Import Test Cases)   │
+  │ shared/testing/actions       │          │   - NavigationBar.goToHome() │
+  │ shared/testing/fixtures      │          │   - Step.loginAsAdmin()      │
+  └──────────────────────────────┘          │   - Spectra.dismissBanner()  │
+                                            └──────────────────────────────┘
+\`\`\`
+
+---
+
+## 3. Running Tests via Nx
+
+\`\`\`bash
+# Run all feature E2E suites in parallel
+pnpm nx run-many -t e2e
+
+# Run only E2E tests for features changed in PR
+pnpm nx affected -t e2e
+
+# Run E2E for a specific feature on Android
+pnpm nx run auth-${e2eFolderName}:e2e --configuration=android
+
+# Run type check across all E2E projects
+pnpm nx run-many -t type-check
+# Or standard TypeScript compilation
+pnpm type-check
+\`\`\`
+`;
+        fs.writeFileSync(path.join(cwd, "ARCHITECTURE.md"), archDocContent, "utf-8");
+        // 8. Safely append to root README.md (do not overwrite existing content)
+        const rootReadmePath = path.join(cwd, "README.md");
+        const archSection = `\n## E2E Testing Architecture (TestSpectra)\n\nThis workspace uses TestSpectra's **Centralized Configuration, Distributed Implementation** architecture.\nDetailed architecture, folder map, and zero-import mechanics are documented in:  \n👉 **[ARCHITECTURE.md](./ARCHITECTURE.md)**\n\n- **Run all E2E tests**: \`pnpm nx run-many -t e2e\`\n- **Run affected E2E tests**: \`pnpm nx affected -t e2e\`\n- **Type-check E2E suites**: \`pnpm type-check\`\n`;
+        if (fs.existsSync(rootReadmePath)) {
+            const existing = fs.readFileSync(rootReadmePath, "utf-8");
+            if (!existing.includes("ARCHITECTURE.md")) {
+                fs.appendFileSync(rootReadmePath, archSection, "utf-8");
+            }
+        }
+        else {
+            const readmeContent = `# ${projectName}\n\nAutomated cross-platform E2E testing powered by [TestSpectra](https://github.com/testspectra).\n${archSection}`;
+            fs.writeFileSync(rootReadmePath, readmeContent, "utf-8");
+        }
         console.log(`\n\x1b[32m[TestSpectra]\x1b[0m Enterprise Nx Monorepo initialized successfully!`);
         console.log(`\x1b[36m- Centralized Configuration:\x1b[0m ./spectra.config.ts`);
         console.log(`\x1b[36m- Centralized App Data/Cache:\x1b[0m ./.testspectra/`);
         console.log(`\x1b[36m- Shared Testing Library:\x1b[0m ./${sharedTestingRelPath}`);
+        console.log(`\x1b[36m- Architecture Documentation:\x1b[0m ./ARCHITECTURE.md`);
         console.log(`\x1b[36m- Initialized Features (${featureE2eDirs.length}):\x1b[0m\n  ${featureE2eDirs.map((d) => path.relative(cwd, d)).join("\n  ")}`);
         return;
     }
     // --- STANDALONE / DEFAULT PROJECT FLOW ---
-    const projectName = path.basename(cwd);
     copyRecursive(templateDir, cwd);
     if (!isInternalWorkspace) {
         const pnpmWorkspacePath = path.join(cwd, "pnpm-workspace.yaml");
@@ -367,6 +449,49 @@ export async function initCommand(options = {}) {
         }
     }
     TypeGenerator.writeDeclarationFiles(cwd);
+    // Standalone Architecture Documentation
+    const standaloneArchDoc = `# TestSpectra Project Architecture
+
+This project is built with the TestSpectra testing framework.
+
+## Structure & File Map
+- \`./spectra.config.ts\`: Typed runner configuration.
+- \`./specs/\`: Layered test cases (\`specs/<Suite>/<CaseId>/\` with \`web.test.ts\`, \`android.test.ts\`, \`ios.test.ts\`).
+- \`./page-objects/\`: Page Object models per platform.
+- \`./steps/\`: Business flows accessible globally via \`Step.*\`.
+- \`./actions/\`: Atomic actions accessible globally via \`Spectra.*\`.
+- \`./fixtures/\`: JSON fixtures accessible globally via \`Fixture.*\`.
+- \`./global-hooks/\`: Global suite lifecycle hooks.
+- \`./.testspectra/\`: Auto-generated ambient typings and local runtime cache.
+
+## Execution
+\`\`\`bash
+# Run web test suite
+pnpm test
+
+# Run Android / iOS
+pnpm spectra run --target android
+pnpm spectra run --target ios
+
+# Type check
+pnpm type-check
+\`\`\`
+`;
+    fs.writeFileSync(path.join(cwd, "ARCHITECTURE.md"), standaloneArchDoc, "utf-8");
+    // Safely update root README.md (do not overwrite existing content)
+    const standaloneReadmePath = path.join(cwd, "README.md");
+    const standaloneArchSection = `\n## E2E Testing Architecture (TestSpectra)\n\nDetailed test architecture and folder map are documented in:  \n👉 **[ARCHITECTURE.md](./ARCHITECTURE.md)**\n\n- **Run tests**: \`pnpm test\`\n- **Type-check**: \`pnpm type-check\`\n`;
+    if (fs.existsSync(standaloneReadmePath)) {
+        const existing = fs.readFileSync(standaloneReadmePath, "utf-8");
+        if (!existing.includes("ARCHITECTURE.md")) {
+            fs.appendFileSync(standaloneReadmePath, standaloneArchSection, "utf-8");
+        }
+    }
+    else {
+        const standaloneReadme = `# ${projectName}\n\nTestSpectra automated testing project.\n${standaloneArchSection}`;
+        fs.writeFileSync(standaloneReadmePath, standaloneReadme, "utf-8");
+    }
     console.log(`\x1b[32m[TestSpectra]\x1b[0m Initialized project from template successfully!`);
+    console.log(`\x1b[32m[TestSpectra]\x1b[0m Generated documentation at ./ARCHITECTURE.md`);
     console.log(`\x1b[32m[TestSpectra]\x1b[0m Generated ambient multi-platform types in .testspectra/types/`);
 }

package/package.json

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