testdriverai 7.1.3 → 7.2.0

package/docs/v7/features/data-driven-testing.mdx

@@ -0,0 +1,441 @@
+---
+title: "Data-Driven Testing"
+description: "Build maintainable test suites with reusable code and dynamic test data"
+icon: "table"
+---
+
+Scale your test suite with reusable code patterns and dynamic data to reduce duplication and maintain consistency across thousands of tests.
+
+## Code Snippets for Reusability
+
+Scale your test suite with reusable code snippets to reduce duplication and maintain consistency:
+
+<Tabs>
+  <Tab title="Helper Functions">
+    ```javascript test/helpers/auth.js
+    // Reusable authentication helpers
+    export async function login(testdriver, { email, password }) {
+      await testdriver.find('email input').type(email);
+      await testdriver.find('password input').type(password);
+      await testdriver.find('login button').click();
+      await testdriver.assert('logged in successfully');
+    }
+
+    export async function logout(testdriver) {
+      await testdriver.find('user menu').click();
+      await testdriver.find('logout button').click();
+    }
+    ```
+
+    ```javascript test/checkout.test.js
+    import { login } from './helpers/auth.js';
+
+    test('checkout flow', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+      await login(testdriver, { 
+        email: 'user@example.com',
+        password: 'password123' 
+      });
+      // Continue with checkout test
+    });
+    ```
+  </Tab>
+
+  <Tab title="Page Objects">
+    ```javascript test/pages/LoginPage.js
+    export class LoginPage {
+      constructor(testdriver) {
+        this.testdriver = testdriver;
+      }
+
+      async login(email, password) {
+        await this.testdriver.find('email input').type(email);
+        await this.testdriver.find('password input').type(password);
+        await this.testdriver.find('submit button').click();
+      }
+
+      async assertError(message) {
+        await this.testdriver.assert(`error message shows "${message}"`);
+      }
+    }
+    ```
+
+    ```javascript test/auth.test.js
+    import { LoginPage } from './pages/LoginPage.js';
+
+    test('invalid login shows error', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+      const loginPage = new LoginPage(testdriver);
+      
+      await loginPage.login('invalid@test.com', 'wrong');
+      await loginPage.assertError('Invalid credentials');
+    });
+    ```
+  </Tab>
+
+  <Tab title="Custom Commands">
+    ```javascript test/commands/navigation.js
+    export function addNavigationCommands(testdriver) {
+      testdriver.navigateTo = async (section) => {
+        await testdriver.find(`${section} nav link`).click();
+        await testdriver.assert(`${section} page is loaded`);
+      };
+
+      testdriver.searchFor = async (query) => {
+        await testdriver.find('search input').type(query);
+        await testdriver.find('search button').click();
+        await testdriver.assert('search results are displayed');
+      };
+
+      return testdriver;
+    }
+    ```
+
+    ```javascript test/search.test.js
+    import { addNavigationCommands } from './commands/navigation.js';
+
+    test('search functionality', async (context) => {
+      let { testdriver } = await chrome(context, { url });
+      testdriver = addNavigationCommands(testdriver);
+      
+      await testdriver.searchFor('laptop');
+      // Custom command used
+    });
+    ```
+  </Tab>
+</Tabs>
+
+<Check>
+  Reusable snippets reduce test maintenance time by up to 70% in large test suites.
+</Check>
+
+## Dynamic Variables for Data-Driven Tests
+
+Scale your testing with dynamic data to cover more scenarios:
+
+<Tabs>
+  <Tab title="Environment Variables">
+    ```javascript
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+
+    test('multi-environment testing', async (context) => {
+      const env = process.env.TEST_ENV || 'staging';
+      const urls = {
+        dev: 'https://dev.myapp.com',
+        staging: 'https://staging.myapp.com',
+        production: 'https://myapp.com'
+      };
+
+      const { testdriver } = await chrome(context, { 
+        url: urls[env] 
+      });
+
+      await testdriver.assert('app is running');
+    });
+    ```
+
+    ```bash
+    # Run against different environments
+    TEST_ENV=dev npx vitest run
+    TEST_ENV=staging npx vitest run
+    TEST_ENV=production npx vitest run
+    ```
+  </Tab>
+
+  <Tab title="Test Fixtures">
+    ```javascript test/fixtures/users.js
+    export const testUsers = [
+      { email: 'admin@test.com', role: 'admin' },
+      { email: 'user@test.com', role: 'user' },
+      { email: 'guest@test.com', role: 'guest' }
+    ];
+
+    export const products = [
+      { name: 'Laptop', price: 999 },
+      { name: 'Mouse', price: 29 },
+      { name: 'Keyboard', price: 89 }
+    ];
+    ```
+
+    ```javascript test/permissions.test.js
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+    import { testUsers } from './fixtures/users.js';
+
+    test.each(testUsers)('$role can access dashboard', async ({ email, role }, context) => {
+      const { testdriver } = await chrome(context, { url });
+      
+      await testdriver.find('email input').type(email);
+      await testdriver.find('password input').type('password123');
+      await testdriver.find('login button').click();
+      
+      if (role === 'admin') {
+        await testdriver.assert('admin panel is visible');
+      } else {
+        await testdriver.assert('user dashboard is visible');
+      }
+    });
+    ```
+  </Tab>
+
+  <Tab title="Dynamic Data Generation">
+    ```javascript
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+    import { faker } from '@faker-js/faker';
+
+    test('user registration with dynamic data', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+
+      // Generate unique test data for each run
+      const userData = {
+        firstName: faker.person.firstName(),
+        lastName: faker.person.lastName(),
+        email: faker.internet.email(),
+        password: faker.internet.password({ length: 12 })
+      };
+
+      await testdriver.find('first name input').type(userData.firstName);
+      await testdriver.find('last name input').type(userData.lastName);
+      await testdriver.find('email input').type(userData.email);
+      await testdriver.find('password input').type(userData.password);
+      await testdriver.find('register button').click();
+
+      await testdriver.assert('registration successful');
+      console.log('Registered user:', userData.email);
+    });
+    ```
+
+    ```bash
+    npm install --save-dev @faker-js/faker
+    ```
+  </Tab>
+</Tabs>
+
+<Card title="Dynamic Variables Best Practices" icon="lightbulb">
+  - **Environment configs:** Store URLs, credentials, and settings in env vars
+  - **Test fixtures:** Maintain reusable test data in separate files
+  - **Data generators:** Use libraries like Faker for unique test data
+  - **Parameterization:** Test multiple scenarios with `test.each()`
+  - **CI/CD integration:** Pass dynamic values via environment variables
+</Card>
+
+## Secure Secrets Management
+
+Protect sensitive data in your tests with built-in secrets handling:
+
+<Tabs>
+  <Tab title="Secret Type Option">
+    ```javascript
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+
+    test('login with secret password', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+
+      await testdriver.find('email input').type('user@example.com');
+      
+      // Password is never logged or cached
+      await testdriver.find('password input').type(process.env.TEST_PASSWORD, { 
+        secret: true 
+      });
+      
+      await testdriver.find('login button').click();
+      await testdriver.assert('logged in successfully');
+    });
+    ```
+
+    <Check>
+      The `secret: true` option prevents sensitive data from appearing in logs, dashcam replays, or cache entries.
+    </Check>
+  </Tab>
+
+  <Tab title="Environment Variables">
+    ```javascript
+    // .env.test
+    TEST_PASSWORD=my-secret-password
+    TEST_API_KEY=sk-1234567890abcdef
+    TEST_CREDIT_CARD=4111111111111111
+
+    // test/auth.test.js
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+
+    test('secure authentication', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+
+      // Load secrets from environment
+      await testdriver.find('password input').type(
+        process.env.TEST_PASSWORD, 
+        { secret: true }
+      );
+
+      await testdriver.find('api key input').type(
+        process.env.TEST_API_KEY,
+        { secret: true }
+      );
+    });
+    ```
+
+    ```bash
+    # Install dotenv for local development
+    npm install --save-dev dotenv
+
+    # Load in test setup
+    import 'dotenv/config';
+    ```
+  </Tab>
+
+  <Tab title="CI/CD Secrets">
+    ```yaml .github/workflows/test.yml
+    name: E2E Tests
+
+    on: [push, pull_request]
+
+    jobs:
+      test:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v3
+          - uses: actions/setup-node@v3
+          - run: npm install
+          - run: npx vitest run
+            env:
+              TD_API_KEY: ${{ secrets.TD_API_KEY }}
+              TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+              TEST_API_KEY: ${{ secrets.TEST_API_KEY }}
+    ```
+
+    Configure secrets in your CI/CD platform:
+    - **GitHub:** Settings → Secrets and variables → Actions
+    - **GitLab:** Settings → CI/CD → Variables
+    - **CircleCI:** Project Settings → Environment Variables
+  </Tab>
+
+  <Tab title="Helper Functions">
+    ```javascript test/helpers/secrets.js
+    // Centralized secret handling
+    export function getSecret(key) {
+      const value = process.env[key];
+      if (!value) {
+        throw new Error(`Secret ${key} not found in environment`);
+      }
+      return value;
+    }
+
+    export async function typeSecret(testdriver, selector, secretKey) {
+      const value = getSecret(secretKey);
+      await testdriver.find(selector).type(value, { secret: true });
+    }
+    ```
+
+    ```javascript test/payment.test.js
+    import { typeSecret } from './helpers/secrets.js';
+
+    test('payment form', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+
+      await typeSecret(testdriver, 'credit card input', 'TEST_CREDIT_CARD');
+      await typeSecret(testdriver, 'cvv input', 'TEST_CVV');
+      
+      await testdriver.find('submit payment').click();
+    });
+    ```
+  </Tab>
+</Tabs>
+
+<Warning>
+  Never hardcode secrets in test files or commit them to version control. Always use environment variables or secure secret management systems.
+</Warning>
+
+## Familiar Test Syntax
+
+TestDriver works with the test frameworks you already know:
+
+<Tabs>
+  <Tab title="Vitest">
+    ```javascript
+    import { test, describe, beforeAll, afterAll } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+
+    describe('My Feature', () => {
+      test('should work', async (context) => {
+        const { testdriver } = await chrome(context, { url });
+        await testdriver.find('button').click();
+      });
+    });
+    ```
+  </Tab>
+
+  <Tab title="Jest">
+    ```javascript
+    import { chrome } from 'testdriverai/presets';
+
+    describe('My Feature', () => {
+      test('should work', async () => {
+        const { testdriver } = await chrome({ url });
+        await testdriver.find('button').click();
+      });
+    });
+    ```
+  </Tab>
+
+  <Tab title="Mocha">
+    ```javascript
+    import { chrome } from 'testdriverai/presets';
+
+    describe('My Feature', function() {
+      it('should work', async function() {
+        const { testdriver } = await chrome(this, { url });
+        await testdriver.find('button').click();
+      });
+    });
+    ```
+  </Tab>
+</Tabs>
+
+## Existing Systems Integration
+
+Drop TestDriver into your current workflow without disruption:
+
+```javascript
+import { test, expect } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('integrates with existing assertions', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+
+  // Use TestDriver's AI assertions
+  await testdriver.assert('welcome message is visible');
+
+  // Or use traditional assertions
+  const button = await testdriver.find('submit button');
+  expect(button.coordinates).toBeDefined();
+  expect(button.text).toContain('Submit');
+
+  // Mix and match as needed
+  const element = await testdriver.exec('js', 'document.title');
+  expect(element).toBe('My App');
+});
+```
+
+## Learn More
+
+<CardGroup cols={2}>
+  <Card
+    title="Vitest Integration"
+    icon="flask-vial"
+    href="/v7/guides/vitest"
+  >
+    Complete Vitest guide
+  </Card>
+
+  <Card
+    title="Continuous Testing"
+    icon="arrows-spin"
+    href="/v7/features/continuous-testing"
+  >
+    CI/CD integration and scaling
+  </Card>
+</CardGroup>

package/docs/v7/features/easy-to-write.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Easy to Write"
+title: "Natural Language Syntax"
 description: "Natural language testing that feels like describing what you want, not programming"
 icon: "feather"
 ---
@@ -61,7 +61,7 @@ All element methods are chainable:
 
 ## Familiar Syntax
 
-TestDriver integrates seamlessly with the test frameworks you already know and love:
+TestDriver uses `vitest` to run tests with a familiar syntax you already know and love:
 
 <Tabs>
   <Tab title="Vitest">
@@ -78,36 +78,6 @@ TestDriver integrates seamlessly with the test frameworks you already know and l
     });
     ```
   </Tab>
-
-  <Tab title="Jest">
-    ```javascript
-    import { chrome } from 'testdriverai/presets';
-
-    test('my test', async () => {
-      const { testdriver } = await chrome({
-        url: 'https://example.com'
-      });
-
-      await testdriver.find('button').click();
-    });
-    ```
-  </Tab>
-
-  <Tab title="Mocha">
-    ```javascript
-    import { chrome } from 'testdriverai/presets';
-
-    describe('My Suite', () => {
-      it('should work', async function() {
-        const { testdriver } = await chrome(this, {
-          url: 'https://example.com'
-        });
-
-        await testdriver.find('button').click();
-      });
-    });
-    ```
-  </Tab>
 </Tabs>
 
 No need to learn a new DSL or configuration format. TestDriver works with your existing test infrastructure.
@@ -217,47 +187,6 @@ test('user can login', async () => {
 ```
 </CodeGroup>
 
-## Progressive Complexity
-
-Choose your level of control:
-
-<CardGroup cols={3}>
-  <Card title="Presets (Easiest)" icon="rocket">
-    One-line setup for common scenarios:
-
-    ```javascript
-    const { testdriver } = await chrome(context, {
-      url: 'https://example.com'
-    });
-    ```
-
-    [Learn more](/v7/progressive-apis/PROVISION)
-  </Card>
-
-  <Card title="Hooks (Flexible)" icon="link">
-    More control with composable hooks:
-
-    ```javascript
-    const client = useTestDriver(context);
-    const dashcam = useDashcam(context, client);
-    ```
-
-    [Learn more](/v7/progressive-apis/HOOKS)
-  </Card>
-
-  <Card title="Core (Full Control)" icon="code">
-    Manual control over everything:
-
-    ```javascript
-    const client = new TestDriver(apiKey);
-    await client.connect();
-    await client.find('button');
-    ```
-
-    [Learn more](/v7/progressive-apis/PROGRESSIVE_DISCLOSURE)
-  </Card>
-</CardGroup>
-
 ## Zero Boilerplate
 
 Presets handle all the setup and teardown automatically: