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

package/templates/docs/ARCHITECTURE.nx.md

@@ -0,0 +1,119 @@
+# 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: From Inside the Feature Directory (Direct CLI)
+
+```bash
+# Navigate to the feature e2e folder
+cd __SAMPLE_FEATURE_E2E_PATH__
+
+# Run all specs in this feature
+pnpm spectra run
+
+# Run a specific test case by ID (platform is already picked via -t, no need for the file path)
+pnpm spectra run TC-AUTH-01 -t web
+
+# 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
+```