testdriverai 6.2.2 → 7.1.0

package/docs/v7/presets/webapp.mdx

@@ -0,0 +1,396 @@
+---
+title: "Web App Preset"
+sidebarTitle: "Web App"
+description: "Generic preset for testing web applications"
+icon: "globe"
+---
+
+## Overview
+
+The `webApp()` preset provides a generic interface for testing web applications. It currently uses Chrome under the hood but provides a more semantic API for web app testing.
+
+## Quick Start
+
+```javascript
+import { test } from 'vitest';
+import { webApp } from 'testdriverai/presets';
+
+test('web app test', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://myapp.com',
+    browser: 'chrome'
+  });
+  
+  await testdriver.find('Login button').click();
+});
+```
+
+## Signature
+
+```typescript
+webApp(context, options): Promise<WebAppResult>
+```
+
+### Parameters
+
+<ParamField path="context" type="object" required>
+  Vitest test context - automatically passed to your test function
+</ParamField>
+
+<ParamField path="options" type="object">
+  Configuration options for web app testing
+
+  <Expandable title="properties">
+    <ParamField path="url" type="string" default="http://testdriver-sandbox.vercel.app/">
+      URL to navigate to when browser launches
+    </ParamField>
+
+    <ParamField path="browser" type="'chrome'" default="chrome">
+      Browser to use (currently only Chrome is supported)
+    </ParamField>
+
+    <ParamField path="maximized" type="boolean" default={true}>
+      Start browser in maximized window mode
+    </ParamField>
+
+    <ParamField path="guest" type="boolean" default={true}>
+      Use browser guest/incognito mode (no profile data)
+    </ParamField>
+
+    <ParamField path="dashcam" type="boolean" default={true}>
+      Enable Dashcam test recording
+    </ParamField>
+
+    <ParamField path="os" type="'linux' | 'mac' | 'windows'" default="linux">
+      Target operating system for the test
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Returns
+
+<ResponseField name="testdriver" type="TestDriver" required>
+  TestDriver instance ready to use
+</ResponseField>
+
+<ResponseField name="dashcam" type="Dashcam">
+  Dashcam instance for test recording (if enabled)
+</ResponseField>
+
+## Examples
+
+### Basic Web App Testing
+
+```javascript
+import { test } from 'vitest';
+import { webApp } from 'testdriverai/presets';
+
+test('user login flow', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://myapp.com/login'
+  });
+  
+  await testdriver.find('email input').type('user@example.com');
+  await testdriver.find('password input').type('password123');
+  await testdriver.find('Login button').click();
+  
+  await testdriver.assert('Dashboard is visible');
+});
+```
+
+### E-commerce Testing
+
+```javascript
+import { test } from 'vitest';
+import { webApp } from 'testdriverai/presets';
+
+test('product purchase', async (context) => {
+  const { testdriver, dashcam } = await webApp(context, {
+    url: 'https://shop.example.com'
+  });
+  
+  // Search for product
+  await testdriver.find('search input').type('laptop');
+  await testdriver.find('search button').click();
+  
+  // Select product
+  await testdriver.find('first product result').click();
+  
+  // Add to cart
+  await testdriver.find('Add to Cart').click();
+  
+  // Proceed to checkout
+  await testdriver.find('Cart icon').click();
+  await testdriver.find('Checkout').click();
+  
+  await testdriver.assert('Checkout page loaded');
+});
+```
+
+### SPA Navigation
+
+```javascript
+import { test } from 'vitest';
+import { webApp } from 'testdriverai/presets';
+
+test('single page app routing', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://spa.example.com'
+  });
+  
+  // Navigate through SPA routes
+  await testdriver.find('About link').click();
+  await testdriver.assert('About page content is visible');
+  
+  await testdriver.find('Products link').click();
+  await testdriver.assert('Products page content is visible');
+  
+  await testdriver.find('Contact link').click();
+  await testdriver.assert('Contact form is visible');
+});
+```
+
+### Form Validation
+
+```javascript
+import { test } from 'vitest';
+import { webApp } from 'testdriverai/presets';
+
+test('form validation errors', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://myapp.com/register'
+  });
+  
+  // Submit empty form
+  await testdriver.find('Submit button').click();
+  
+  // Verify validation errors
+  await testdriver.assert('Email is required error is shown');
+  await testdriver.assert('Password is required error is shown');
+  
+  // Fill valid data
+  await testdriver.find('email input').type('test@example.com');
+  await testdriver.find('password input').type('SecurePass123!');
+  
+  // Submit again
+  await testdriver.find('Submit button').click();
+  
+  await testdriver.assert('Registration successful');
+});
+```
+
+### API Integration Testing
+
+```javascript
+import { test } from 'vitest';
+import { webApp } from 'testdriverai/presets';
+
+test('data fetching and display', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://api-demo.example.com'
+  });
+  
+  // Trigger data fetch
+  await testdriver.find('Load Data button').click();
+  
+  // Wait for loading state
+  await testdriver.assert('Loading spinner is visible');
+  
+  // Wait for data to load
+  await testdriver.assert('Data table is populated');
+  
+  // Verify specific data
+  await testdriver.assert('First row contains expected data');
+});
+```
+
+### Responsive Design Testing
+
+```javascript
+import { test } from 'vitest';
+import { webApp } from 'testdriverai/presets';
+
+test('mobile menu', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://responsive.example.com',
+    maximized: false // Start in default window size
+  });
+  
+  // Resize to mobile
+  await testdriver.exec('sh', 'xdotool getactivewindow windowsize 375 667', 5000);
+  
+  // Open mobile menu
+  await testdriver.find('hamburger menu icon').click();
+  
+  // Navigate in mobile menu
+  await testdriver.find('Products in mobile menu').click();
+  
+  await testdriver.assert('Products page is displayed');
+});
+```
+
+## Browser Support
+
+Currently, `webApp()` only supports Chrome:
+
+```javascript
+// ✅ Supported
+const { testdriver } = await webApp(context, {
+  browser: 'chrome'
+});
+
+// ❌ Not yet supported
+const { testdriver } = await webApp(context, {
+  browser: 'firefox' // Throws error
+});
+```
+
+Future releases will add support for Firefox, Edge, and Safari.
+
+## What It Does
+
+When you call `webApp()`, it automatically:
+
+1. **Validates Browser** - Checks that requested browser is supported
+2. **Delegates to Browser Preset** - Currently uses the Chrome preset
+3. **Returns Standard Interface** - Provides consistent API regardless of browser
+
+All the heavy lifting is done by the underlying browser preset (currently `chrome()`).
+
+## When to Use
+
+Use `webApp()` when:
+
+- You want browser-agnostic code (for future multi-browser support)
+- You're testing a generic web application
+- You prefer semantic naming over specific browser names
+
+Use `chrome()` directly when:
+
+- You need Chrome-specific features
+- You want explicit browser control
+- You're testing Chrome extensions or Chrome-specific behavior
+
+## Using with provision()
+
+The `webApp()` preset can also be called via the unified `provision()` function:
+
+```javascript
+import { provision } from 'testdriverai/presets';
+
+test('using provision', async (context) => {
+  const { testdriver } = await provision('webapp', {
+    url: 'https://example.com',
+    browser: 'chrome'
+  }, context);
+  
+  // Same functionality as webApp() directly
+});
+```
+
+## Migration Path
+
+If you're currently using `chrome()` for web app testing, you can easily switch to `webApp()`:
+
+```javascript
+// Before
+import { chrome } from 'testdriverai/presets';
+const { testdriver } = await chrome(context, { url });
+
+// After
+import { webApp } from 'testdriverai/presets';
+const { testdriver } = await webApp(context, { url, browser: 'chrome' });
+```
+
+The behavior is identical, but `webApp()` provides a more generic interface for future browser additions.
+
+## Common Patterns
+
+### Authentication Flow
+
+```javascript
+test('login and navigate', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://myapp.com'
+  });
+  
+  // Login
+  await testdriver.find('email').type('user@example.com');
+  await testdriver.find('password').type('password');
+  await testdriver.find('Login').click();
+  
+  // Wait for redirect
+  await testdriver.assert('Dashboard is loaded');
+  
+  // Navigate authenticated area
+  await testdriver.find('Settings').click();
+  await testdriver.assert('Settings page is loaded');
+});
+```
+
+### File Upload
+
+```javascript
+test('upload file', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://upload.example.com'
+  });
+  
+  // Click upload button
+  await testdriver.find('Upload file button').click();
+  
+  // Type file path in file dialog
+  await testdriver.type('/tmp/test-file.pdf');
+  await testdriver.pressKeys(['enter']);
+  
+  // Verify upload
+  await testdriver.assert('File uploaded successfully');
+});
+```
+
+### Search and Filter
+
+```javascript
+test('search with filters', async (context) => {
+  const { testdriver } = await webApp(context, {
+    url: 'https://catalog.example.com'
+  });
+  
+  // Enter search query
+  await testdriver.find('search input').type('laptop');
+  
+  // Apply filters
+  await testdriver.find('Price filter').click();
+  await testdriver.find('$500 - $1000').click();
+  
+  await testdriver.find('Brand filter').click();
+  await testdriver.find('Dell').click();
+  
+  // Submit search
+  await testdriver.find('Search button').click();
+  
+  await testdriver.assert('Filtered results are displayed');
+});
+```
+
+## Error Handling
+
+```javascript
+test('handles unsupported browser', async (context) => {
+  try {
+    const { testdriver } = await webApp(context, {
+      browser: 'firefox' // Not yet supported
+    });
+  } catch (error) {
+    expect(error.message).toContain('not yet implemented');
+  }
+});
+```
+
+## See Also
+
+- [Provision API](/v7/progressive-apis/PROVISION) - Overview of all presets
+- [Chrome Preset](/v7/presets/chrome) - Direct Chrome testing
+- [VS Code Preset](/v7/presets/vscode) - Testing VS Code extensions
+- [Electron Preset](/v7/presets/electron) - Testing Electron apps
+- [Vitest Integration](/v7/guides/vitest) - Complete Vitest setup guide