intellitester 0.2.34 → 0.2.40

package/README.md

@@ -12,6 +12,33 @@ npx playwright install chromium
 npx playwright install
 ```
 
+## AI Assistant Integration
+
+IntelliTester can generate comprehensive documentation for AI assistants (Claude, GPT, etc.) to help them write effective tests.
+
+### Generate Guide
+
+Use the `guide` command to create an `intellitester_guide.md` file in your project:
+
+```bash
+intellitester guide
+# Or use the alias:
+intellitester init-guide
+```
+
+This generates a detailed reference document that AI assistants can read to understand:
+- All action types and their syntax
+- Target selector options (testId, text, css, xpath, role, description)
+- Variable interpolation and built-in generators
+- Best practices for test organization
+- Common testing patterns (login flows, form submissions, email verification)
+- Configuration options for tests, workflows, and pipelines
+
+The guide is particularly useful when:
+- Using AI assistants to generate test files
+- Onboarding team members who use AI coding tools
+- Maintaining consistent test patterns across a team
+
 ## Editor Configuration
 
 IntelliTester provides JSON schemas for YAML configuration files to enable autocomplete and validation in VS Code and other editors.
@@ -25,7 +52,8 @@ Add this to your `.vscode/settings.json` (or workspace settings):
   "yaml.schemas": {
     "./node_modules/intellitester/schemas/intellitester.config.schema.json": "intellitester.config.yaml",
     "./node_modules/intellitester/schemas/test.schema.json": "*.test.yaml",
-    "./node_modules/intellitester/schemas/workflow.schema.json": "*.workflow.yaml"
+    "./node_modules/intellitester/schemas/workflow.schema.json": "*.workflow.yaml",
+    "./node_modules/intellitester/schemas/pipeline.schema.json": "*.pipeline.yaml"
   }
 }
 ```
@@ -45,7 +73,8 @@ If you're working on IntelliTester itself or want to use local schemas, use thes
   "yaml.schemas": {
     "./schemas/intellitester.config.schema.json": "intellitester.config.yaml",
     "./schemas/test.schema.json": "*.test.yaml",
-    "./schemas/workflow.schema.json": "*.workflow.yaml"
+    "./schemas/workflow.schema.json": "*.workflow.yaml",
+    "./schemas/pipeline.schema.json": "*.pipeline.yaml"
   }
 }
 ```
@@ -84,6 +113,37 @@ When execution pauses, you can:
 - Examine selectors and elements
 - Continue execution when ready
 
+## Fast-Fail Conditions (errorIf)
+
+Use `errorIf` to fail a step immediately when a condition is met, without waiting for timeouts:
+
+```yaml
+steps:
+  - type: tap
+    target: { testId: login-btn }
+    errorIf: not-found  # Fail immediately if element not found
+
+  - type: assert
+    target: { testId: welcome-msg }
+    errorIf: not-visible  # Fail if element exists but not visible
+
+  - type: input
+    target: { testId: email }
+    value: test@example.com
+    errorIf: disabled  # Fail if input is disabled
+```
+
+**Available conditions:**
+
+| Condition | Description |
+|-----------|-------------|
+| `not-found` | Element doesn't exist in DOM |
+| `not-visible` | Element exists but not visible |
+| `disabled` | Element is disabled |
+| `empty` | Element has no text content |
+
+> **Note:** `testId` now matches `data-testid`, `id`, and `class` attributes in that order.
+
 ## Resource Cleanup
 
 IntelliTester automatically tracks resources created during tests and cleans them up after execution. This ensures tests don't leave behind database rows, files, users, or other artifacts.
@@ -215,3 +275,126 @@ intellitester run --session-id my-session --track-dir .intellitester/track
 ```
 
 If `INTELLITESTER_TRACK_URL` is set, `track()` will send HTTP requests and also append to the track file (when available). If only the file is set, `track()` writes locally.
+
+## Pipelines & Workflows
+
+IntelliTester supports three levels of test organization:
+
+### Test Files (`*.test.yaml`)
+
+A single test with a sequence of steps. The most basic building block.
+
+```yaml
+name: Login Test
+platform: web
+variables:
+  EMAIL: test@example.com
+steps:
+  - type: navigate
+    value: /login
+  - type: input
+    target: { testId: email }
+    value: ${EMAIL}
+  - type: input
+    target: { testId: password }
+    value: secret123
+  - type: tap
+    target: { text: Sign In }
+  - type: assert
+    target: { text: Welcome }
+```
+
+### Workflows (`*.workflow.yaml`)
+
+Multiple tests run in sequence with a shared browser session. Tests share cookies, local storage, and authentication state.
+
+```yaml
+name: User Onboarding
+platform: web
+config:
+  web:
+    baseUrl: http://localhost:3000
+continueOnFailure: false
+tests:
+  - file: ./signup.test.yaml
+    id: signup
+  - file: ./verify-email.test.yaml
+    id: verify
+    variables:
+      EMAIL: ${signup.EMAIL}
+  - file: ./complete-profile.test.yaml
+```
+
+### Pipelines (`*.pipeline.yaml`)
+
+Multiple workflows with shared browser session, dependencies, and variables. Pipelines orchestrate complex test suites with control over execution order and failure handling.
+
+```yaml
+name: Full E2E Suite
+platform: web
+on_failure: skip  # skip | fail | ignore
+cleanup_on_failure: true
+config:
+  web:
+    baseUrl: http://localhost:3000
+  webServer:
+    command: npm run dev
+    url: http://localhost:3000
+    reuseExistingServer: true
+    timeout: 30000
+workflows:
+  - file: ./auth.workflow.yaml
+    id: auth
+    on_failure: fail  # Stop pipeline if auth fails
+
+  - file: ./dashboard.workflow.yaml
+    id: dashboard
+    depends_on: [auth]
+    variables:
+      USER_TOKEN: ${auth.TOKEN}
+
+  - file: ./settings.workflow.yaml
+    depends_on: [auth]
+    on_failure: ignore  # Continue even if settings tests fail
+
+  - file: ./cleanup.workflow.yaml
+    depends_on: [dashboard, settings]
+```
+
+### Pipeline Features
+
+**Workflow Properties:**
+
+| Property | Description |
+|----------|-------------|
+| `file` | Path to the workflow file (required) |
+| `id` | Identifier for referencing in `depends_on` and variable passing |
+| `depends_on` | Array of workflow IDs that must complete first |
+| `variables` | Variables to inject, can reference outputs from dependencies |
+| `on_failure` | How to handle failure: `skip`, `fail`, or `ignore` |
+
+**Failure Handling (`on_failure`):**
+
+- `skip` - Skip dependent workflows, continue independent ones (default)
+- `fail` - Stop the entire pipeline immediately
+- `ignore` - Continue as if the workflow succeeded
+
+**Web Server (`config.webServer`):**
+
+Start a dev server automatically before running tests:
+
+```yaml
+config:
+  webServer:
+    command: npm run dev        # Command to start server
+    url: http://localhost:3000  # Wait for this URL
+    reuseExistingServer: true   # Use existing if running
+    timeout: 30000              # Startup timeout (ms)
+```
+
+**Shared Browser Session:**
+
+All workflows in a pipeline share the same browser context, preserving:
+- Cookies and session storage
+- Authentication state
+- Local storage data

package/dist/{chunk-EPN5OT5I.js → chunk-2KTVH32L.js}

@@ -1,4 +1,4 @@
-import { loadTestDefinition } from './chunk-64V2U2Y4.js';
+import { loadTestDefinition } from './chunk-ML5CBUF7.js';
 import { track } from './chunk-2BFRS6ZZ.js';
 import { loadCleanupHandlers, executeCleanup, saveFailedCleanup } from './chunk-O4H5QO5P.js';
 import { NumberDictionary, uniqueNamesGenerator, adjectives, animals } from 'unique-names-generator';
@@ -1036,7 +1036,11 @@ var resolveUrl = (value, baseUrl) => {
   }
 };
 var resolveLocator = (page, locator) => {
-  if (locator.testId) return page.getByTestId(locator.testId);
+  if (locator.testId) {
+    return page.locator(
+      `[data-testid="${locator.testId}"], #${CSS.escape(locator.testId)}, .${CSS.escape(locator.testId)}`
+    ).first();
+  }
   if (locator.text) return page.getByText(locator.text);
   if (locator.css) return page.locator(locator.css);
   if (locator.xpath) return page.locator(`xpath=${locator.xpath}`);
@@ -1048,6 +1052,49 @@ var resolveLocator = (page, locator) => {
   if (locator.description) return page.getByText(locator.description);
   throw new Error("No usable selector found for locator");
 };
+var checkErrorIf = async (page, locator, errorIf) => {
+  if (!errorIf) return;
+  const handle = resolveLocator(page, locator);
+  switch (errorIf) {
+    case "not-found": {
+      const count = await handle.count();
+      if (count === 0) {
+        throw new Error(`errorIf: Element not found in DOM (testId/selector: ${JSON.stringify(locator)})`);
+      }
+      break;
+    }
+    case "not-visible": {
+      const count = await handle.count();
+      if (count > 0) {
+        const isVisible = await handle.isVisible();
+        if (!isVisible) {
+          throw new Error(`errorIf: Element exists but is not visible (testId/selector: ${JSON.stringify(locator)})`);
+        }
+      }
+      break;
+    }
+    case "disabled": {
+      const count = await handle.count();
+      if (count > 0) {
+        const isDisabled = await handle.isDisabled();
+        if (isDisabled) {
+          throw new Error(`errorIf: Element is disabled (testId/selector: ${JSON.stringify(locator)})`);
+        }
+      }
+      break;
+    }
+    case "empty": {
+      const count = await handle.count();
+      if (count > 0) {
+        const text = await handle.textContent();
+        if (!text || text.trim() === "") {
+          throw new Error(`errorIf: Element has no text content (testId/selector: ${JSON.stringify(locator)})`);
+        }
+      }
+      break;
+    }
+  }
+};
 async function ensureScreenshotDir(dir) {
   await fs.mkdir(dir, { recursive: true });
 }
@@ -1379,6 +1426,7 @@ async function executeActionWithRetry(page, action, index, options) {
           if (debugMode) {
             console.log(`[DEBUG] Tapping element:`, action.target);
           }
+          await checkErrorIf(page, action.target, action.errorIf);
           await runTap(page, action.target);
           break;
         }
@@ -1388,17 +1436,20 @@ async function executeActionWithRetry(page, action, index, options) {
             console.log(`[DEBUG] Inputting value into element:`, action.target);
             console.log(`[DEBUG] Value: ${interpolated}`);
           }
+          await checkErrorIf(page, action.target, action.errorIf);
           await runInput(page, action.target, action.value, context);
           break;
         }
         case "clear": {
           if (debugMode) console.log(`[DEBUG] Clearing element:`, action.target);
+          await checkErrorIf(page, action.target, action.errorIf);
           const handle = resolveLocator(page, action.target);
           await handle.clear();
           break;
         }
         case "hover": {
           if (debugMode) console.log(`[DEBUG] Hovering element:`, action.target);
+          await checkErrorIf(page, action.target, action.errorIf);
           const handle = resolveLocator(page, action.target);
           await handle.hover();
           break;
@@ -1406,18 +1457,21 @@ async function executeActionWithRetry(page, action, index, options) {
         case "select": {
           const interpolated = interpolateVariables(action.value, context.variables);
           if (debugMode) console.log(`[DEBUG] Selecting: ${interpolated}`);
+          await checkErrorIf(page, action.target, action.errorIf);
           const handle = resolveLocator(page, action.target);
           await handle.selectOption(interpolated);
           break;
         }
         case "check": {
           if (debugMode) console.log(`[DEBUG] Checking:`, action.target);
+          await checkErrorIf(page, action.target, action.errorIf);
           const handle = resolveLocator(page, action.target);
           await handle.check();
           break;
         }
         case "uncheck": {
           if (debugMode) console.log(`[DEBUG] Unchecking:`, action.target);
+          await checkErrorIf(page, action.target, action.errorIf);
           const handle = resolveLocator(page, action.target);
           await handle.uncheck();
           break;
@@ -1425,6 +1479,7 @@ async function executeActionWithRetry(page, action, index, options) {
         case "press": {
           if (debugMode) console.log(`[DEBUG] Pressing key: ${action.key}`);
           if (action.target) {
+            await checkErrorIf(page, action.target, action.errorIf);
             const handle = resolveLocator(page, action.target);
             await handle.press(action.key);
           } else {
@@ -1434,6 +1489,7 @@ async function executeActionWithRetry(page, action, index, options) {
         }
         case "focus": {
           if (debugMode) console.log(`[DEBUG] Focusing:`, action.target);
+          await checkErrorIf(page, action.target, action.errorIf);
           const handle = resolveLocator(page, action.target);
           await handle.focus();
           break;
@@ -1446,13 +1502,20 @@ async function executeActionWithRetry(page, action, index, options) {
               console.log(`[DEBUG] Expected text contains: ${interpolated}`);
             }
           }
+          await checkErrorIf(page, action.target, action.errorIf);
           await runAssert(page, action.target, action.value, context);
           break;
         }
         case "wait":
+          if (action.target && action.errorIf) {
+            await checkErrorIf(page, action.target, action.errorIf);
+          }
           await runWait(page, action);
           break;
         case "scroll":
+          if (action.target && action.errorIf) {
+            await checkErrorIf(page, action.target, action.errorIf);
+          }
           await runScroll(page, action);
           break;
         case "screenshot":
@@ -1547,6 +1610,9 @@ async function executeActionWithRetry(page, action, index, options) {
         }
         case "waitForSelector": {
           const wsAction = action;
+          if (wsAction.errorIf) {
+            await checkErrorIf(page, wsAction.target, wsAction.errorIf);
+          }
           const handle = resolveLocator(page, wsAction.target);
           const timeout = wsAction.timeout ?? 3e4;
           if (debugMode) {
@@ -1690,7 +1756,7 @@ async function executeActionWithRetry(page, action, index, options) {
               });
             }
           } else {
-            const { loadWorkflowDefinition, loadTestDefinition: loadTestDefinition2 } = await import('./loader-JSTO36JJ.js');
+            const { loadWorkflowDefinition, loadTestDefinition: loadTestDefinition2 } = await import('./loader-B46MGIWG.js');
             const workflowPath = path2.resolve(process.cwd(), branchToExecute.workflow);
             const workflowDir = path2.dirname(workflowPath);
             if (debugMode) {
@@ -2646,7 +2712,7 @@ async function runTestInWorkflow(test, page, context, options, _workflowDir, wor
                 if (debugMode) {
                   console.log(`  [DEBUG] waitForBranch: loading workflow from ${workflowPath}`);
                 }
-                const { loadWorkflowDefinition } = await import('./loader-JSTO36JJ.js');
+                const { loadWorkflowDefinition } = await import('./loader-B46MGIWG.js');
                 const nestedWorkflow = await loadWorkflowDefinition(workflowPath);
                 if (branch.variables) {
                   for (const [key, value] of Object.entries(branch.variables)) {
@@ -3275,5 +3341,5 @@ Collected ${serverResources.length} server-tracked resources`);
 }
 
 export { createAIProvider, createTestContext, generateFillerText, generateRandomEmail, generateRandomPhone, generateRandomPhoto, generateRandomUsername, getBrowserLaunchOptions, initFileTracking, interpolateVariables, killServer, mergeFileTrackedResources, runWebTest, runWorkflow, runWorkflowWithContext, setupAppwriteTracking, startTrackingServer, startWebServer };
-//# sourceMappingURL=chunk-EPN5OT5I.js.map
-//# sourceMappingURL=chunk-EPN5OT5I.js.map
+//# sourceMappingURL=chunk-2KTVH32L.js.map
+//# sourceMappingURL=chunk-2KTVH32L.js.map