testdriverai 7.0.0 → 7.1.1

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

@@ -0,0 +1,351 @@
+---
+title: "Easy to Write"
+description: "Natural language testing that feels like describing what you want, not programming"
+icon: "feather"
+---
+
+Writing tests with TestDriver is intuitive and straightforward. No more brittle CSS selectors or complex XPath expressions - just describe what you want in plain English.
+
+## Natural Language Selectors
+
+Find elements the way humans think about them:
+
+<CodeGroup>
+```javascript TestDriver - Natural Language
+// ✅ Readable and maintainable
+await testdriver.find('submit button').click();
+await testdriver.find('email input in the login form').type('user@example.com');
+await testdriver.find('delete button in the top right corner').click();
+```
+
+```javascript Traditional - CSS Selectors
+// ❌ Fragile and cryptic
+await page.locator('#root > div > form > div:nth-child(2) > button').click();
+await page.locator('input[name="email"][data-testid="login-form-email"]').type('user@example.com');
+await page.locator('.header-actions > .btn-danger:last-child').click();
+```
+</CodeGroup>
+
+<Tip>
+  Natural language selectors are resilient to UI changes. If a button moves or the DOM structure changes, the same description often still works.
+</Tip>
+
+## Chainable API
+
+Write cleaner, more readable test code with method chaining:
+
+```javascript
+// Find and interact in one fluid motion
+await testdriver.find('Login button').click();
+await testdriver.find('username field').type('admin');
+await testdriver.find('password field').type('secret', { secret: true });
+await testdriver.find('submit').click();
+
+// Also works with hover interactions
+await testdriver.find('Products menu').hover();
+await testdriver.find('Laptops submenu').click();
+
+// And other actions
+await testdriver.find('checkbox item').doubleClick();
+await testdriver.find('context menu item').rightClick();
+```
+
+All element methods are chainable:
+- `.click()` - Click the element
+- `.hover()` - Hover over the element
+- `.doubleClick()` - Double-click the element
+- `.rightClick()` - Right-click the element
+- `.mouseDown()` - Press mouse button down
+- `.mouseUp()` - Release mouse button
+- `.type(text)` - Type text into the element
+
+## Familiar Syntax
+
+TestDriver integrates seamlessly with the test frameworks you already know and love:
+
+<Tabs>
+  <Tab title="Vitest">
+    ```javascript
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+
+    test('my test', async (context) => {
+      const { testdriver } = await chrome(context, {
+        url: 'https://example.com'
+      });
+
+      await testdriver.find('button').click();
+    });
+    ```
+  </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.
+
+## Full TypeScript Support
+
+First-class TypeScript support with complete IntelliSense and type safety:
+
+```typescript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('typed test', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com'
+  });
+
+  const element = await testdriver.find('button');
+
+  // ✅ Autocomplete works perfectly
+  element.coordinates.x;
+  element.coordinates.y;
+  element.text;
+  element.confidence;
+
+  // ❌ TypeScript catches errors at compile time
+  element.invalidProperty; // Error: Property 'invalidProperty' does not exist
+});
+```
+
+<Card title="Type Definitions" icon="code">
+  TestDriver includes comprehensive TypeScript definitions for all APIs, methods, and return types. Your IDE will provide intelligent autocomplete and inline documentation.
+</Card>
+
+## AI-Powered Assertions
+
+Verify application state using natural language:
+
+```javascript
+// Verify UI state
+await testdriver.assert('the login page is displayed');
+await testdriver.assert('submit button is visible and enabled');
+
+// Verify content
+await testdriver.assert('the page title is "Welcome"');
+await testdriver.assert('success message says "Account created successfully"');
+
+// Verify interactions
+await testdriver.assert('the checkbox is checked');
+await testdriver.assert('the dropdown shows "United States"');
+
+// Verify visual state
+await testdriver.assert('the button is blue');
+await testdriver.assert('the loading spinner is not visible');
+```
+
+No need to write complex selectors and assertions. Just describe what should be true.
+
+## Clean Test Code
+
+Compare the readability of TestDriver vs traditional approaches:
+
+<CodeGroup>
+```javascript TestDriver - Clean & Readable
+test('user can login', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://myapp.com/login'
+  });
+
+  await testdriver.find('email input').type('user@example.com');
+  await testdriver.find('password input').type('secret', { secret: true });
+  await testdriver.find('Login button').click();
+
+  await testdriver.assert('Dashboard is visible');
+});
+```
+
+```javascript Traditional - Verbose & Complex
+test('user can login', async () => {
+  await page.goto('https://myapp.com/login');
+
+  const emailInput = await page.waitForSelector(
+    'input[type="email"][name="email"]',
+    { state: 'visible', timeout: 30000 }
+  );
+  await emailInput.type('user@example.com');
+
+  const passwordInput = await page.waitForSelector(
+    'input[type="password"][name="password"]',
+    { state: 'visible', timeout: 30000 }
+  );
+  await passwordInput.type('secret');
+
+  const loginButton = await page.waitForSelector(
+    'button[type="submit"]',
+    { state: 'visible', timeout: 30000 }
+  );
+  await loginButton.click();
+
+  await page.waitForSelector('.dashboard', {
+    state: 'visible',
+    timeout: 30000
+  });
+  const dashboard = await page.$('.dashboard');
+  expect(dashboard).toBeTruthy();
+});
+```
+</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:
+
+```javascript
+test('minimal test', async (context) => {
+  // One line to set up everything:
+  // - Authentication
+  // - Sandbox provisioning
+  // - Browser launch
+  // - Navigation
+  // - Dashcam recording
+  // - Automatic cleanup
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com'
+  });
+
+  // Write your test
+  await testdriver.find('button').click();
+
+  // No cleanup needed - automatic!
+});
+```
+
+<Check>
+  The preset automatically disconnects and cleans up resources when your test completes, even if it fails.
+</Check>
+
+## Real-World Example
+
+Here's a complete, real-world test that showcases TestDriver's simplicity:
+
+```javascript
+import { test, expect } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('user can checkout', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://shop.example.com'
+  });
+
+  // Add items to cart
+  await testdriver.find('Add to Cart button on the first product').click();
+  await testdriver.assert('Cart badge shows 1 item');
+
+  // Go to checkout
+  await testdriver.find('Cart icon').click();
+  await testdriver.find('Checkout button').click();
+
+  // Fill shipping form
+  await testdriver.find('Full name input').type('John Doe');
+  await testdriver.find('Address input').type('123 Main St');
+  await testdriver.find('City input').type('Springfield');
+  await testdriver.find('State dropdown').click();
+  await testdriver.find('California option').click();
+
+  // Submit order
+  await testdriver.find('Place Order button').click();
+
+  // Verify success
+  await testdriver.assert('Order confirmation page is displayed');
+  await testdriver.assert('Thank you message is visible');
+});
+```
+
+Notice:
+- No CSS selectors or IDs
+- No explicit waits
+- No manual setup/teardown
+- Reads like a test plan
+- Self-documenting code
+
+## Get Started
+
+<CardGroup cols={2}>
+  <Card
+    title="Quick Start"
+    icon="rocket"
+    href="/v7/getting-started/quickstart"
+  >
+    Get up and running in 2 minutes
+  </Card>
+
+  <Card
+    title="API Reference"
+    icon="book"
+    href="/v7/api/client"
+  >
+    Complete API documentation
+  </Card>
+</CardGroup>