@testspectra/cli 1.1.8-rc.9 → 1.1.11-rc.3

package/templates/docs/ARCHITECTURE.nx.md

@@ -0,0 +1,147 @@
+# 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 (`./__SHARED_TESTING_REL_PATH__`)
+Provides cross-feature reusable test entities with **100% zero-import global resolution**:
+- `page-objects/`: Shared Page Object models (e.g. NavigationBar, AppHeader).
+- `support/steps/`: Cross-feature business step flows (e.g. `Step.loginAsAdmin()`).
+- `support/actions/`: Custom atomic actions (e.g. `Spectra.dismissBanner()`).
+- `fixtures/`: Common test data and environment configurations (e.g. `Fixture.appConfig`).
+
+### Distributed Feature E2E Modules (__FEATURE_COUNT__ Features)
+__FEATURE_MODULES_SECTION__
+
+---
+
+## 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>/__E2E_FOLDER_NAME__/page-objects/`, `<feature>/__E2E_FOLDER_NAME__/support/steps/`, `<feature>/__E2E_FOLDER_NAME__/support/actions/`
+   - **Shared Library Entities**: `./__SHARED_TESTING_REL_PATH__/page-objects/`, `./__SHARED_TESTING_REL_PATH__/support/steps/`, `./__SHARED_TESTING_REL_PATH__/support/actions/`, `./__SHARED_TESTING_REL_PATH__/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 (__SHARED_TESTING_REL_PATH__/page-objects/NavigationBar)
+  await NavigationBar.goToLogin();
+
+  // 2. Consumed from Shared Testing Library (__SHARED_TESTING_REL_PATH__/support/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 (__SHARED_TESTING_REL_PATH__/support/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-__E2E_FOLDER_NAME__:e2e
+
+# 2. Run E2E for a specific feature on ANDROID or IOS
+pnpm nx run auth-__E2E_FOLDER_NAME__:e2e --configuration=android
+pnpm nx run auth-__E2E_FOLDER_NAME__:e2e --configuration=ios
+
+# 3. Run E2E for a specific feature in HEADLESS browser mode
+pnpm nx run auth-__E2E_FOLDER_NAME__: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: Directly via TestSpectra CLI (`spectra run`)
+
+You can execute tests directly via CLI from either the **Monorepo Root** or inside a **Feature Directory**.  
+*Zero file-path overhead: You do NOT need to provide long file globs like `"packages/features/auth/**/*.spec.web.ts"` — just specify the TC ID or Suite name directly.*
+
+```bash
+# === From Monorepo Root ===
+
+# 1. Run ALL tests across the entire monorepo
+# (Spawns configured dev servers in parallel, checks readiness, runs tests, tears down)
+pnpm spectra run
+
+# 2. Run all tests for a specific host / dev server
+pnpm spectra run --host sso
+
+# 3. Run a specific test case by ID (simple TC ID, no long file path needed)
+pnpm spectra run --host sso --spec TC-AUTH-01
+
+# Or as a direct positional argument:
+pnpm spectra run --host sso TC-AUTH-01
+
+# 4. Run an entire suite by suite name
+pnpm spectra run --host sso --spec Auth
+# Or:
+pnpm spectra run --host sso Auth
+
+# 5. Run in Headed mode (visible Chrome window)
+pnpm spectra run --host sso --headed
+
+# === From Inside Feature Directory (cd __SAMPLE_FEATURE_E2E_PATH__) ===
+
+# Run all specs in this feature
+pnpm spectra run
+
+# Run a specific test case by ID
+pnpm spectra run TC-AUTH-01 -t web
+
+# Run a specific suite by name
+pnpm spectra run Auth -t web
+
+# Target Android device or emulator
+pnpm spectra run -t android
+
+# Target iOS simulator or device
+pnpm spectra run -t ios
+```
+
+---
+
+## 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
+```