@testspectra/cli 1.1.8-rc.18 → 1.1.8-rc.20

package/dist/commands/init.js

@@ -78,26 +78,6 @@ function ensurePnpmWorkspaceIncludes(pnpmWorkspacePath, targetPath) {
         }
     }
 }
-function renderArchitectureDoc(templatePath, replacements) {
-    let content = fs.readFileSync(templatePath, 'utf-8');
-    for (const [token, value] of Object.entries(replacements)) {
-        content = content.replaceAll(token, value);
-    }
-    return content;
-}
-function buildFeatureModulesSection(cwd, featureE2eDirs, e2eFolderName) {
-    return featureE2eDirs
-        .map((d) => {
-        const rel = path.relative(cwd, d).replace(/\\/g, '/');
-        const name = path.basename(path.dirname(d));
-        const e2eName = `${name}-${e2eFolderName}`;
-        return `- \`./${rel}\` (**${name}**, Nx Project: \`${e2eName}\`):
-  - \`specs/\`: Feature test cases (\`specs/<SuiteName>/<CaseId>/\` with \`web.test.ts\`, \`android.test.ts\`, \`ios.test.ts\`).
-  - \`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\`).`;
-    })
-        .join('\n');
-}
 function ensureVsCodeExtensions(cwd) {
     const vscodeDir = path.join(cwd, '.vscode');
     const extFile = path.join(vscodeDir, 'extensions.json');
@@ -267,7 +247,6 @@ export async function initCommand(options = {}) {
         p.cancel(chalk.red(`Template directory not found: ${templateDir}`));
         return;
     }
-    const docsTemplateDir = path.join(path.dirname(templateDir), 'docs');
     // 2. Resolve CLI dependency version
     let cliVersion = '^1.0.65';
     try {
@@ -579,15 +558,136 @@ export async function initCommand(options = {}) {
         // 7. Generate Ambient Types in ROOT only
         TypeGenerator.writeDeclarationFiles(cwd);
         ensureVsCodeExtensions(cwd);
-        const archDocContent = renderArchitectureDoc(path.join(docsTemplateDir, 'ARCHITECTURE.nx.md'), {
-            __SHARED_TESTING_REL_PATH__: sharedTestingRelPath,
-            __FEATURE_COUNT__: String(featureE2eDirs.length),
-            __FEATURE_MODULES_SECTION__: buildFeatureModulesSection(cwd, featureE2eDirs, e2eFolderName),
-            __E2E_FOLDER_NAME__: e2eFolderName,
-            __SAMPLE_FEATURE_E2E_PATH__: featureE2eDirs.length > 0
-                ? path.relative(cwd, featureE2eDirs[0]).replace(/\\/g, '/')
-                : `modules/auth/${e2eFolderName}`,
-        });
+        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/\`: Local test project cache, runtime metadata, auto-generated master TSConfig (\`.testspectra/tsconfig.json\`), platform sub-configs (\`.testspectra/tsconfig/\`), and universal ambient types (\`.testspectra/types/\`). Global binaries and drivers are managed at \`~/.testspectra/drivers/\`.
+- \`./nx.json\`: Nx target defaults with execution caching and inputs.
+- \`./pnpm-workspace.yaml\`: Monorepo package glob definitions.
+- \`./tsconfig.json\`: Solution-style TypeScript orchestrator referencing \`./.testspectra/tsconfig.json\`.
+
+### Centralized Shared Testing 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));
+            const e2eName = `${name}-${e2eFolderName}`;
+            return `- \`./${rel}\` (**${name}**, Nx Project: \`${e2eName}\`):
+  - \`specs/\`: Feature test cases (\`specs/<SuiteName>/<CaseId>/\` with \`web.test.ts\`, \`android.test.ts\`, \`ios.test.ts\`).
+  - \`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\`).`;
+        })
+            .join('\n')}
+
+---
+
+## 2. Zero-Import Consumption Flow & Mechanics
+
+TestSpectra completely eliminates boilerplate \`import\` statements across all test specs, steps, and page objects.
+
+### How It Works:
+1. **Centralized Ambient Aggregation**:  
+   TestSpectra Language Service Plugin & CLI automatically scan:
+   - **Local Feature Entities**: \`<feature>/${e2eFolderName}/page-objects/\`, \`<feature>/${e2eFolderName}/steps/\`, \`<feature>/${e2eFolderName}/actions/\`
+   - **Shared Library Entities**: \`./${sharedTestingRelPath}/page-objects/\`, \`./${sharedTestingRelPath}/steps/\`, \`./${sharedTestingRelPath}/actions/\`, \`./${sharedTestingRelPath}/fixtures/\`
+2. **Ambient Typing Generation**:  
+   These are compiled into \`.testspectra/types/web.d.ts\`, \`android.d.ts\`, \`ios.d.ts\`, \`fixtures.d.ts\`.
+3. **Instant IDE Autocomplete & Zero Clutter**:  
+   Specs consume both local feature objects and shared library utilities globally.
+
+### Code Example:
+\`\`\`typescript
+// packages/features/auth/e2e/specs/Auth/TC-AUTH-01/web.test.ts
+// 🌟 NOTICE: 100% Zero-Import & Flat Execution! (No import statement, no describe wrapper)
+
+it("should navigate via shared header and login with local POM", async () => {
+  // 1. Consumed from Shared Testing Library (${sharedTestingRelPath}/page-objects/NavigationBar)
+  await NavigationBar.goToLogin();
+
+  // 2. Consumed from Shared Testing Library (${sharedTestingRelPath}/steps/loginAsAdmin)
+  await Step.loginAsAdmin();
+
+  // 3. Consumed from Local Feature POM (page-objects/LoginPage)
+  await LoginPage.flashAlert.shouldBeVisible();
+  await LoginPage.flashAlert.shouldContainText("Welcome");
+
+  // 4. Consumed from Shared Testing Library Custom Action (${sharedTestingRelPath}/actions/dismissBanner)
+  await Spectra.dismissBanner();
+});
+\`\`\`
+
+---
+
+## 3. How to Run Tests
+
+You can execute tests either from the **Monorepo Root via Nx** or directly inside each **Feature Directory via CLI**:
+
+### Option A: From Root Monorepo via Nx (Recommended for CI & Team Workflows)
+
+\`\`\`bash
+# 1. Run E2E for a SPECIFIC feature module (e.g. auth)
+pnpm nx run auth-${e2eFolderName}:e2e
+
+# 2. Run E2E for a specific feature on ANDROID or IOS
+pnpm nx run auth-${e2eFolderName}:e2e --configuration=android
+pnpm nx run auth-${e2eFolderName}:e2e --configuration=ios
+
+# 3. Run E2E for a specific feature in HEADLESS browser mode
+pnpm nx run auth-${e2eFolderName}:e2e --configuration=headless
+
+# 4. Run ALL feature E2E suites across the entire monorepo in parallel
+pnpm nx run-many -t e2e
+
+# 5. Run only E2E tests for features modified in current Git branch / PR
+pnpm nx affected -t e2e
+\`\`\`
+
+### Option B: From Inside the Feature Directory (Direct CLI)
+
+\`\`\`bash
+# Navigate to the feature e2e folder
+cd ${featureE2eDirs.length > 0 ? path.relative(cwd, featureE2eDirs[0]).replace(/\\/g, '/') : `modules/auth/${e2eFolderName}`}
+
+# Run all specs in this feature
+pnpm spectra run
+
+# Run a specific test case file
+pnpm spectra run specs/Auth/TC-AUTH-01/web.test.ts
+
+# Target Android device or emulator
+pnpm spectra run --target android
+
+# Run in headed / interactive browser mode
+pnpm spectra run --no-headless
+\`\`\`
+
+---
+
+## 4. Type Checking & Validation
+
+\`\`\`bash
+# Type check all E2E projects via Nx
+pnpm nx run-many -t type-check
+
+# Or standard TypeScript project references build from root
+pnpm type-check
+# or: npx tsc -b
+\`\`\`
+`;
         fs.writeFileSync(path.join(cwd, 'ARCHITECTURE.md'), archDocContent, 'utf-8');
         // 8. Ensure root .gitignore ignores .testspectra/ and *.tsbuildinfo
         const rootGitignorePath = path.join(cwd, '.gitignore');
@@ -642,7 +742,34 @@ export async function initCommand(options = {}) {
     TypeGenerator.writeDeclarationFiles(cwd);
     ensureVsCodeExtensions(cwd);
     // Standalone Architecture Documentation
-    fs.copyFileSync(path.join(docsTemplateDir, 'ARCHITECTURE.default.md'), path.join(cwd, 'ARCHITECTURE.md'));
+    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`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.1.8-rc.18",
+  "version": "1.1.8-rc.20",
   "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,9 +26,9 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@testspectra/matchers": "^1.1.8-rc.18",
-    "@testspectra/react": "^1.1.8-rc.18",
-    "@testspectra/skills": "^1.1.8-rc.18",
+    "@testspectra/matchers": "^1.1.8-rc.20",
+    "@testspectra/react": "^1.1.8-rc.20",
+    "@testspectra/skills": "^1.1.8-rc.20",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "dotenv": "^16.4.5",
@@ -38,10 +38,10 @@
     "zod": "^3.23.8"
   },
   "optionalDependencies": {
-    "@testspectra/cli-darwin-arm64": "1.1.8-rc.18",
-    "@testspectra/cli-linux-x64": "1.1.8-rc.18",
-    "@testspectra/cli-win32-arm64": "1.1.8-rc.18",
-    "@testspectra/cli-win32-x64": "1.1.8-rc.18"
+    "@testspectra/cli-darwin-arm64": "1.1.8-rc.20",
+    "@testspectra/cli-linux-x64": "1.1.8-rc.20",
+    "@testspectra/cli-win32-arm64": "1.1.8-rc.20",
+    "@testspectra/cli-win32-x64": "1.1.8-rc.20"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",

package/templates/default/package.json

@@ -17,8 +17,8 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.8-rc.18",
-    "@testspectra/matchers": "^1.1.8-rc.18",
+    "@testspectra/cli": "^1.1.8-rc.20",
+    "@testspectra/matchers": "^1.1.8-rc.20",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",