testdriverai 7.1.0 → 7.1.2

package/docs/v7/guides/ci-cd/travis.mdx

@@ -1,438 +0,0 @@
----
-title: "Travis CI"
-description: "Run TestDriver tests in Travis CI"
-icon: "circle-check"
----
-
-<Warning>
-Travis CI has significantly reduced its free tier. Consider using [GitHub Actions](/v7/guides/ci-cd/github-actions) or [GitLab CI](/v7/guides/ci-cd/gitlab) instead.
-</Warning>
-
-## Basic Setup
-
-Create `.travis.yml`:
-
-```yaml
-language: node_js
-node_js:
-  - 18
-
-cache:
-  directories:
-    - node_modules
-
-env:
-  global:
-    - secure: "encrypted_api_key_here"
-
-script:
-  - npx vitest
-
-after_script:
-  - cat test-results/*.log || true
-```
-
-## Add API Key
-
-### Using Travis CLI
-
-Install Travis CLI:
-
-```bash
-gem install travis
-```
-
-Encrypt API key:
-
-```bash
-# Login to Travis
-travis login --pro
-
-# Encrypt TD_API_KEY
-travis encrypt TD_API_KEY="your-api-key" --add env.global
-```
-
-This automatically adds the encrypted key to `.travis.yml`:
-
-```yaml
-env:
-  global:
-    - secure: "very_long_encrypted_string"
-```
-
-### Using Travis Web UI
-
-1. Go to repository settings on travis-ci.com
-2. Find **Environment Variables** section
-3. Add variable:
-   - Name: `TD_API_KEY`
-   - Value: Your API key from [dashboard.testdriver.ai](https://dashboard.testdriver.ai)
-   - Display value in build log: **OFF**
-4. Click **Add**
-
-## Parallel Tests
-
-Use build matrix for parallel execution:
-
-```yaml
-language: node_js
-node_js:
-  - 18
-
-env:
-  global:
-    - secure: "encrypted_api_key"
-  jobs:
-    - SHARD=1/4
-    - SHARD=2/4
-    - SHARD=3/4
-    - SHARD=4/4
-
-cache:
-  directories:
-    - node_modules
-
-script:
-  - npx vitest --shard=$SHARD
-```
-
-## Save Dashcam URLs
-
-Extract replay URLs from test output:
-
-```yaml
-script:
-  - npx vitest 2>&1 | tee test-output.log
-  - grep -o 'https://dashcam.testdriver.ai/[a-zA-Z0-9-]*' test-output.log > dashcam-urls.txt || true
-
-after_failure:
-  - cat dashcam-urls.txt
-```
-
-## Scheduled Builds
-
-Travis doesn't support scheduled builds in config. Configure via web UI:
-
-1. Go to repository settings
-2. Find **Cron Jobs** section
-3. Click **Add**
-4. Branch: `main`
-5. Interval: Daily, Weekly, or Monthly
-6. Click **Add**
-
-## Multiple Node Versions
-
-Test across Node.js versions:
-
-```yaml
-language: node_js
-node_js:
-  - 16
-  - 18
-  - 20
-
-cache:
-  directories:
-    - node_modules
-
-env:
-  global:
-    - secure: "encrypted_api_key"
-
-script:
-  - npx vitest
-```
-
-## Conditional Execution
-
-Skip tests on documentation changes:
-
-```yaml
-language: node_js
-node_js:
-  - 18
-
-cache:
-  directories:
-    - node_modules
-
-env:
-  global:
-    - secure: "encrypted_api_key"
-
-before_script:
-  - |
-    if git diff --name-only $TRAVIS_COMMIT_RANGE | grep -qvE '\.md$'; then
-      echo "Code changes detected, running tests"
-    else
-      echo "Only documentation changed, skipping tests"
-      exit 0
-    fi
-
-script:
-  - npx vitest
-```
-
-## Retry Failed Tests
-
-Travis doesn't have built-in retry. Use vitest retry:
-
-```javascript
-// vitest.config.mjs
-export default defineConfig({
-  test: {
-    retry: 2
-  }
-});
-```
-
-Or wrap command:
-
-```yaml
-script:
-  - npx vitest || npx vitest || npx vitest
-```
-
-## Different OS
-
-Test on Linux and macOS:
-
-```yaml
-language: node_js
-node_js:
-  - 18
-
-os:
-  - linux
-  - osx
-
-cache:
-  directories:
-    - node_modules
-
-env:
-  global:
-    - secure: "encrypted_api_key"
-
-script:
-  - npx vitest
-```
-
-## Stages
-
-Organize pipeline into stages:
-
-```yaml
-language: node_js
-node_js:
-  - 18
-
-cache:
-  directories:
-    - node_modules
-
-env:
-  global:
-    - secure: "encrypted_api_key"
-
-jobs:
-  include:
-    - stage: install
-      script: npm ci
-    
-    - stage: test
-      script: npx vitest
-      env: SHARD=1/4
-    
-    - stage: test
-      script: npx vitest
-      env: SHARD=2/4
-    
-    - stage: test
-      script: npx vitest
-      env: SHARD=3/4
-    
-    - stage: test
-      script: npx vitest
-      env: SHARD=4/4
-
-stages:
-  - install
-  - test
-```
-
-## Artifacts
-
-Travis doesn't have built-in artifact storage. Upload to external service:
-
-```yaml
-after_success:
-  - |
-    if [ "$TRAVIS_PULL_REQUEST" = "false" ]; then
-      # Upload to S3, GitHub Releases, etc.
-      aws s3 cp test-results/ s3://my-bucket/test-results/ --recursive
-    fi
-```
-
-## Notifications
-
-Configure notifications:
-
-```yaml
-notifications:
-  email:
-    recipients:
-      - team@example.com
-    on_success: change  # default: change
-    on_failure: always  # default: always
-  
-  slack:
-    rooms:
-      - secure: "encrypted_slack_webhook"
-    on_success: change
-    on_failure: always
-```
-
-## Timeout
-
-Set script timeout:
-
-```yaml
-script:
-  - travis_wait 30 npx vitest  # Wait up to 30 minutes
-```
-
-## Troubleshooting
-
-### Tests timeout
-
-Default timeout is 10 minutes. Increase:
-
-```yaml
-script:
-  - travis_wait 30 npx vitest
-```
-
-### Build doesn't start
-
-Travis CI free tier has limited capacity. Builds may queue for hours.
-
-### API key not found
-
-Debug environment:
-
-```yaml
-before_script:
-  - echo "Has TD_API_KEY ${TD_API_KEY:+yes}"
-  - node --version
-```
-
-## Complete Example
-
-Full-featured configuration:
-
-```yaml
-language: node_js
-node_js:
-  - 18
-
-cache:
-  directories:
-    - node_modules
-
-env:
-  global:
-    - secure: "encrypted_api_key_here"
-  jobs:
-    - SHARD=1/4
-    - SHARD=2/4
-    - SHARD=3/4
-    - SHARD=4/4
-
-before_install:
-  - npm install -g npm@latest
-
-install:
-  - npm ci
-
-script:
-  - npx vitest --shard=$SHARD 2>&1 | tee test-output.log
-  - grep -o 'https://dashcam.testdriver.ai/[a-zA-Z0-9-]*' test-output.log > dashcam-urls.txt || true
-
-after_failure:
-  - echo "Dashcam URLs:"
-  - cat dashcam-urls.txt || true
-
-after_script:
-  - cat test-results/*.log || true
-
-notifications:
-  email:
-    on_success: change
-    on_failure: always
-
-branches:
-  only:
-    - main
-    - develop
-```
-
-## Migration to GitHub Actions
-
-Travis CI has become less attractive. Here's equivalent GitHub Actions config:
-
-```yaml
-# .github/workflows/test.yml
-name: Tests
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        shard: [1, 2, 3, 4]
-    
-    steps:
-      - uses: actions/checkout@v3
-      
-      - uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-          cache: 'npm'
-      
-      - run: npm ci
-      
-      - run: npx vitest --shard=${{ matrix.shard }}/4
-        env:
-          TD_API_KEY: ${{ secrets.TD_API_KEY }}
-      
-      - uses: actions/upload-artifact@v3
-        if: always()
-        with:
-          name: test-results
-          path: test-results/
-```
-
-See [GitHub Actions guide](/v7/guides/ci-cd/github-actions) for details.
-
-## See Also
-
-<CardGroup cols={2}>
-  <Card title="CI/CD Overview" icon="arrows-spin" href="/v7/guides/ci-cd/overview">
-    CI/CD concepts
-  </Card>
-  
-  <Card title="GitHub Actions" icon="github" href="/v7/guides/ci-cd/github-actions">
-    Recommended alternative
-  </Card>
-  
-  <Card title="GitLab CI" icon="gitlab" href="/v7/guides/ci-cd/gitlab">
-    Another alternative
-  </Card>
-  
-  <Card title="Travis CI Docs" icon="book" href="https://docs.travis-ci.com/">
-    Official docs
-  </Card>
-</CardGroup>

package/scripts/view-test-results.mjs

@@ -1,96 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * TestDriver SDK Test Results Viewer
- * Displays a formatted summary of test results from the JSON output
- */
-
-import fs from "fs";
-import path from "path";
-
-const RESULTS_PATH = "test-results/results.json";
-
-function formatDuration(ms) {
-  if (ms < 1000) return `${ms}ms`;
-  return `${(ms / 1000).toFixed(2)}s`;
-}
-
-function displayResults() {
-  if (!fs.existsSync(RESULTS_PATH)) {
-    console.error("❌ No test results found. Run tests first:");
-    console.error("   npm run test:sdk");
-    process.exit(1);
-  }
-
-  const results = JSON.parse(fs.readFileSync(RESULTS_PATH, "utf8"));
-
-  const total = results.numTotalTests || 0;
-  const passed = results.numPassedTests || 0;
-  const failed = results.numFailedTests || 0;
-  const skipped = results.numPendingTests || 0;
-  const duration = results.testResults?.reduce(
-    (sum, file) => sum + (file.endTime - file.startTime),
-    0,
-  );
-
-  console.log("\n🧪 TestDriver SDK Test Results");
-  console.log("═".repeat(50));
-  console.log(`✅ Passed:   ${passed}/${total}`);
-  console.log(`❌ Failed:   ${failed}/${total}`);
-  console.log(`⏭️  Skipped:  ${skipped}/${total}`);
-  console.log(`⏱️  Duration: ${formatDuration(duration)}`);
-  console.log("═".repeat(50));
-
-  if (failed > 0) {
-    console.log("\n❌ Failed Tests:\n");
-    results.testResults?.forEach((file) => {
-      const failedTests =
-        file.assertionResults?.filter((test) => test.status === "failed") || [];
-
-      if (failedTests.length > 0) {
-        console.log(`📁 ${path.relative(process.cwd(), file.name)}`);
-        failedTests.forEach((test) => {
-          console.log(`   ❌ ${test.title}`);
-          console.log(`      Duration: ${formatDuration(test.duration)}`);
-          if (test.failureMessages?.length > 0) {
-            console.log("\n      Error:");
-            test.failureMessages.forEach((msg) => {
-              // Truncate very long error messages
-              const truncated =
-                msg.length > 500 ? msg.substring(0, 500) + "..." : msg;
-              console.log(
-                "      " + truncated.split("\n").join("\n      ") + "\n",
-              );
-            });
-          }
-        });
-        console.log();
-      }
-    });
-  }
-
-  if (passed > 0) {
-    console.log("✅ Passed Tests:\n");
-    results.testResults?.forEach((file) => {
-      const passedTests =
-        file.assertionResults?.filter((test) => test.status === "passed") || [];
-
-      if (passedTests.length > 0) {
-        console.log(`📁 ${path.relative(process.cwd(), file.name)}`);
-        passedTests.forEach((test) => {
-          console.log(`   ✅ ${test.title} (${formatDuration(test.duration)})`);
-        });
-        console.log();
-      }
-    });
-  }
-
-  console.log("\n📊 View detailed HTML report:");
-  console.log("   npm run test:sdk:report");
-  console.log("   or open: test-results/index.html\n");
-
-  // Exit with error code if tests failed
-  process.exit(failed > 0 ? 1 : 0);
-}
-
-displayResults();

package/src/vitest/extended.mjs

@@ -1,108 +0,0 @@
-/**
- * Extended Vitest test functions for TestDriver
- * 
- * Provides custom test modifiers:
- * - it.once() - Only runs once per sandbox session (skipped on reconnect)
- * 
- * The reconnection state is determined by the TestDriver SDK after connect().
- * 
- * @example
- * import { describe, it, beforeAll, expect } from 'testdriverai/vitest';
- * import TestDriver from 'testdriverai';
- * 
- * describe('My Test', () => {
- *   let testdriver;
- * 
- *   beforeAll(async () => {
- *     testdriver = new TestDriver(process.env.TD_API_KEY);
- *     await testdriver.connect();
- *     
- *     // Store globally so it.once() can access it
- *     globalThis.__testdriver = testdriver;
- *   });
- * 
- *   // Only runs once per sandbox session (skipped on reconnect)
- *   it.once('launch the application', async () => {
- *     await testdriver.exec('sh', 'google-chrome https://example.com', 5000);
- *   });
- * 
- *   // Always runs
- *   it('click the button', async () => {
- *     await testdriver.find('Button').click();
- *   });
- * });
- */
-
-import { afterAll, beforeAll, expect, describe as vitestDescribe, it as vitestIt, test as vitestTest } from 'vitest';
-
-/**
- * Get the TestDriver instance from global state
- * @returns {Object|null} TestDriver instance or null
- */
-function getTestDriver() {
-  return globalThis.__testdriver || null;
-}
-
-/**
- * Check if we're reconnected to an existing sandbox
- * Uses the SDK's isReconnected property set after connect()
- * @returns {boolean} true if reconnected to existing sandbox
- */
-function isReconnected() {
-  const testdriver = getTestDriver();
-  if (!testdriver) {
-    // No testdriver yet - assume new sandbox (setup should run)
-    return false;
-  }
-  return testdriver.isReconnected === true;
-}
-
-/**
- * Extended test function with .once() modifier
- */
-function createExtendedIt(baseIt) {
-  const extended = function(name, fn, timeout) {
-    return baseIt(name, fn, timeout);
-  };
-  
-  // Copy all properties from base it
-  Object.assign(extended, baseIt);
-  
-  /**
-   * it.once() - Only runs once per sandbox session, skipped on reconnect
-   * Use for provisioning, app launch, initial navigation
-   * 
-   * The test checks testdriver.isReconnected which is set by the SDK
-   * after connect() based on whether it reconnected to an existing
-   * sandbox or created a new one.
-   */
-  extended.once = function(name, fn, timeout) {
-    return baseIt(name, async (...args) => {
-      if (isReconnected()) {
-        console.log(`⏭️  Skipping (already run in this sandbox): ${name}`);
-        return;
-      }
-      return fn(...args);
-    }, timeout);
-  };
-  
-  // Preserve skip, only, todo, etc.
-  if (baseIt.skip) extended.skip = baseIt.skip;
-  if (baseIt.only) extended.only = baseIt.only;
-  if (baseIt.todo) extended.todo = baseIt.todo;
-  if (baseIt.concurrent) extended.concurrent = baseIt.concurrent;
-  if (baseIt.sequential) extended.sequential = baseIt.sequential;
-  
-  return extended;
-}
-
-// Create extended test functions
-export const it = createExtendedIt(vitestIt);
-export const test = createExtendedIt(vitestTest);
-
-// Re-export other vitest functions unchanged
-export { afterAll, beforeAll, vitestDescribe as describe, expect };
-
-// Also export utility for manual checking
-  export { getTestDriver, isReconnected };
-

package/src/vitest/index.mjs

@@ -1,64 +0,0 @@
-/**
- * TestDriver Vitest Integration
- * 
- * Main entry point for the TestDriver Vitest plugin.
- * 
- * @example
- * // Basic usage - auto-managed lifecycle
- * import { TestDriver } from 'testdriverai/vitest';
- * 
- * test('my test', async (context) => {
- *   const testdriver = TestDriver(context, { headless: true });
- *   await testdriver.provision.chrome({ url: 'https://example.com' });
- *   await testdriver.find('Login button').click();
- * });
- * 
- * @example
- * // With extended test functions (it.once for setup steps)
- * import { describe, it, expect, TestDriver } from 'testdriverai/vitest';
- * 
- * describe('My Suite', () => {
- *   it.once('launch app', async (context) => {
- *     const testdriver = TestDriver(context);
- *     await testdriver.provision.chrome({ url: 'https://example.com' });
- *   });
- *   
- *   it('click button', async (context) => {
- *     const testdriver = TestDriver(context);
- *     await testdriver.find('Button').click();
- *   });
- * });
- * 
- * @example
- * // Using lifecycle helpers directly
- * import { TestDriver, launchChrome, waitForPage } from 'testdriverai/vitest';
- * 
- * test('custom setup', async (context) => {
- *   const testdriver = TestDriver(context);
- *   await testdriver.ready();
- *   await launchChrome(testdriver, 'https://example.com', { guest: true });
- *   await waitForPage(testdriver, 'Welcome');
- * });
- */
-
-// Core TestDriver hook
-export { TestDriver } from './hooks.mjs';
-
-// Extended Vitest functions
-export {
-    afterAll, beforeAll, describe, expect, getTestDriver,
-    isReconnected, it,
-    test
-} from './extended.mjs';
-
-// Lifecycle helpers
-export {
-    addDashcamLog, authDashcam, launchChrome, launchChromeExtension, launchChromeForTesting, runPostrun, runPrerun, runPrerunChromeExtension, runPrerunChromeForTesting, startDashcam,
-    stopDashcam, waitForPage
-} from './lifecycle.mjs';
-
-// Utility functions
-export {
-    generateTestId, retryAsync, setupEventLogging, sleep, waitFor
-} from './utils.mjs';
-