testdriverai 7.3.11 → 7.3.13

package/ai/skills/testdriver:press-keys/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: testdriver:press-keys
+description: Press keyboard keys and shortcuts
+---
+<!-- Generated from press-keys.mdx. DO NOT EDIT. -->
+
+## Overview
+
+Press one or more keyboard keys simultaneously, useful for keyboard shortcuts, navigation, and special keys.
+
+## Syntax
+
+```javascript
+await testdriver.pressKeys(keys)
+```
+
+## Parameters
+
+<ParamField path="keys" type="Array&lt;string&gt;" required>
+  Array of keys to press simultaneously
+</ParamField>
+
+## Returns
+
+`Promise<void>`
+
+## Common Keys
+
+### Special Keys
+- `'enter'`, `'tab'`, `'escape'`, `'backspace'`, `'delete'`
+- `'space'`, `'up'`, `'down'`, `'left'`, `'right'`
+- `'home'`, `'end'`, `'pageup'`, `'pagedown'`
+
+### Modifier Keys
+- `'ctrl'`, `'alt'`, `'shift'`
+- `'command'` (macOS), `'win'` (Windows)
+- `'ctrlleft'`, `'ctrlright'`, `'shiftleft'`, `'shiftright'`
+
+### Function Keys
+- `'f1'` through `'f24'`
+
+## Examples
+
+### Navigation
+
+```javascript
+// Tab to next field
+await testdriver.pressKeys(['tab']);
+
+// Shift+Tab to previous field
+await testdriver.pressKeys(['shift', 'tab']);
+
+// Arrow keys
+await testdriver.pressKeys(['down']);
+await testdriver.pressKeys(['up']);
+await testdriver.pressKeys(['left']);
+await testdriver.pressKeys(['right']);
+
+// Home/End
+await testdriver.pressKeys(['home']);  // Start of line
+await testdriver.pressKeys(['end']);   // End of line
+
+// Page navigation
+await testdriver.pressKeys(['pagedown']);
+await testdriver.pressKeys(['pageup']);
+```
+
+### Keyboard Shortcuts
+
+```javascript
+// Copy (Ctrl+C / Cmd+C)
+await testdriver.pressKeys(['ctrl', 'c']);
+
+// Paste (Ctrl+V / Cmd+V)
+await testdriver.pressKeys(['ctrl', 'v']);
+
+// Save (Ctrl+S)
+await testdriver.pressKeys(['ctrl', 's']);
+
+// Select All (Ctrl+A)
+await testdriver.pressKeys(['ctrl', 'a']);
+
+// Undo (Ctrl+Z)
+await testdriver.pressKeys(['ctrl', 'z']);
+
+// Redo (Ctrl+Y)
+await testdriver.pressKeys(['ctrl', 'y']);
+
+// Find (Ctrl+F)
+await testdriver.pressKeys(['ctrl', 'f']);
+
+// New tab (Ctrl+T)
+await testdriver.pressKeys(['ctrl', 't']);
+
+// Close tab (Ctrl+W)
+await testdriver.pressKeys(['ctrl', 'w']);
+
+// Refresh (F5 or Ctrl+R)
+await testdriver.pressKeys(['f5']);
+await testdriver.pressKeys(['ctrl', 'r']);
+```
+
+### System Shortcuts
+
+```javascript
+// Alt+Tab (Windows - switch apps)
+await testdriver.pressKeys(['alt', 'tab']);
+
+// Alt+F4 (Windows - close window)
+await testdriver.pressKeys(['alt', 'f4']);
+
+// Win+D (Windows - show desktop)
+await testdriver.pressKeys(['winleft', 'd']);
+
+// Win+L (Windows - lock screen)
+await testdriver.pressKeys(['winleft', 'l']);
+
+// Cmd+Tab (macOS - switch apps)
+await testdriver.pressKeys(['command', 'tab']);
+
+// Cmd+Q (macOS - quit app)
+await testdriver.pressKeys(['command', 'q']);
+```
+
+### Form Submission
+
+```javascript
+// Submit form
+await testdriver.pressKeys(['enter']);
+
+// Cancel/Close
+await testdriver.pressKeys(['escape']);
+
+// Check checkbox
+await testdriver.pressKeys(['space']);
+```
+
+### Text Editing
+
+```javascript
+// Delete selected text
+await testdriver.pressKeys(['delete']);
+
+// Backspace
+await testdriver.pressKeys(['backspace']);
+
+// Select all and delete
+await testdriver.pressKeys(['ctrl', 'a']);
+await testdriver.pressKeys(['delete']);
+
+// Cut text
+await testdriver.pressKeys(['ctrl', 'x']);
+```
+
+## Best Practices
+
+<Check>
+  **Wait after shortcuts**
+  
+  Some keyboard shortcuts trigger animations or navigation:
+  
+  ```javascript
+  await testdriver.pressKeys(['ctrl', 't']); // New tab
+  await new Promise(r => setTimeout(r, 500)); // Wait for tab
+  await testdriver.pressKeys(['ctrl', 'l']); // Focus URL bar
+  ```
+</Check>
+
+<Check>
+  **Use Tab for form navigation**
+  
+  Tab is more reliable than clicking multiple fields:
+  
+  ```javascript
+  const firstField = await testdriver.find('email input');
+  await firstField.click();
+  await testdriver.type('user@example.com');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.type('password123');
+  
+  await testdriver.pressKeys(['tab']);
+  await testdriver.pressKeys(['enter']); // Submit
+  ```
+</Check>
+
+<Warning>
+  **Platform-specific keys**
+  
+  Use the appropriate modifier key for the platform:
+  - Windows/Linux: `'ctrl'`
+  - macOS: `'command'`
+  
+  ```javascript
+  // For cross-platform, you might need to detect OS
+  const modKey = process.platform === 'darwin' ? 'command' : 'ctrl';
+  await testdriver.pressKeys([modKey, 'c']); // Copy
+  ```
+</Warning>
+
+## Use Cases
+
+<AccordionGroup>
+  <Accordion title="Form Navigation">
+    ```javascript
+    // Fill form using Tab
+    const firstField = await testdriver.find('name field');
+    await firstField.click();
+    await testdriver.type('John Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('john@example.com');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('555-0123');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.pressKeys(['enter']); // Submit
+    ```
+  </Accordion>
+  
+  <Accordion title="Text Manipulation">
+    ```javascript
+    const textArea = await testdriver.find('comment textarea');
+    await textArea.click();
+    
+    // Select all existing text
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Copy it
+    await testdriver.pressKeys(['ctrl', 'c']);
+    
+    // Type new text
+    await testdriver.type('New comment');
+    
+    // Undo if needed
+    await testdriver.pressKeys(['ctrl', 'z']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Browser Navigation">
+    ```javascript
+    // Open new tab
+    await testdriver.pressKeys(['ctrl', 't']);
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Focus address bar
+    await testdriver.pressKeys(['ctrl', 'l']);
+    await testdriver.type('https://example.com');
+    await testdriver.pressKeys(['enter']);
+    
+    // Refresh page
+    await testdriver.pressKeys(['f5']);
+    
+    // Close tab
+    await testdriver.pressKeys(['ctrl', 'w']);
+    ```
+  </Accordion>
+  
+  <Accordion title="Application Shortcuts">
+    ```javascript
+    // Save document
+    await testdriver.pressKeys(['ctrl', 's']);
+    
+    // Print
+    await testdriver.pressKeys(['ctrl', 'p']);
+    
+    // Find in page
+    await testdriver.pressKeys(['ctrl', 'f']);
+    await testdriver.type('search term');
+    await testdriver.pressKeys(['escape']); // Close find
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Keyboard Navigation', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    await testdriver.auth();
+    await testdriver.connect();
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('should navigate form with keyboard', async () => {
+    await testdriver.focusApplication('Google Chrome');
+    
+    // Find first field
+    const emailField = await testdriver.find('email input');
+    await emailField.click();
+    await testdriver.type('user@example.com');
+    
+    // Tab through fields
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('John');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('Doe');
+    
+    await testdriver.pressKeys(['tab']);
+    await testdriver.type('password123');
+    
+    // Submit with Enter
+    await testdriver.pressKeys(['tab']);
+    await testdriver.pressKeys(['enter']);
+    
+    await testdriver.assert('form submitted successfully');
+  });
+
+  it('should use keyboard shortcuts', async () => {
+    // Open new browser tab
+    await testdriver.pressKeys(['ctrl', 't']);
+    await new Promise(r => setTimeout(r, 500));
+    
+    // Focus address bar
+    await testdriver.pressKeys(['ctrl', 'l']);
+    await testdriver.type('https://example.com');
+    await testdriver.pressKeys(['enter']);
+    
+    await new Promise(r => setTimeout(r, 2000));
+    
+    // Select all page content
+    await testdriver.pressKeys(['ctrl', 'a']);
+    
+    // Copy
+    await testdriver.pressKeys(['ctrl', 'c']);
+    
+    // Refresh page
+    await testdriver.pressKeys(['f5']);
+  });
+});
+```
+
+## Related Methods
+
+- [`type()`](/v7/type) - Type text
+- [`click()`](/v7/click) - Click elements
+- [`scroll()`](/v7/scroll) - Scroll pages

package/ai/skills/testdriver:quickstart/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: testdriver:quickstart
+description: Run your first computer-use test in minutes.
+---
+<!-- Generated from quickstart.mdx. DO NOT EDIT. -->
+
+TestDriver makes it easy to write automated computer-use tests for web browsers, desktop apps, and more. Follow the directions below to run your first TestDriver test.
+
+<Tip><a href="https://discord.com/invite/cWDFW8DzPm" target="_blank" rel="noreferrer">Join our Discord</a> if you have any questions or need help getting started!</Tip>
+
+<Tabs>
+  <Tab title="Automatic Setup">
+
+    Get started quickly with the TestDriver CLI.
+
+    <Steps>
+      <Step title="Install TestDriver">
+
+        Use `npx` to quickly set up an example project:
+
+        ```bash
+        npx testdriverai init
+        ```
+
+        This will walk you through creating a new project folder, installing dependencies, and setting up your API key.
+
+      </Step>
+      
+      <Step title="Run Your Test">
+
+        TestDriver uses Vitest as the test runner. To run your test, use:
+        
+        ```bash
+        vitest run
+        ```
+
+        This will spawn a sandbox, launch Chrome, and run the example test!
+
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="Manual Setup">
+
+    Install TestDriver and manually create the files yourself.
+
+    <Steps>
+      <Step title="Create a TestDriver Account">
+
+        You will need a TestDriver account to get an API key.
+
+        <Card
+          title="Get an API Key"
+          icon="user-plus"
+          href="https://console.testdriver.ai/team"
+          arrow
+          horizontal
+        >
+          Start with 60 free device minutes, no credit-card required!
+        </Card>
+
+      </Step>
+      <Step title="Install Dependencies">
+
+        Install Vitest and TestDriver as dev dependencies:
+
+        ```bash
+        npm install --save-dev vitest testdriverai
+        ```
+
+      </Step>
+      <Step title="Create a vitest.config.js File">
+
+        In your project root, create a `vitest.config.js` file with the following content:
+
+        ```js vitest.config.js
+        import TestDriver from 'testdriverai/vitest';
+        import { defineConfig } from 'vitest/config';
+
+        export default defineConfig({
+          test: {
+            testTimeout: 900000,
+            hookTimeout: 900000,
+            disableConsoleIntercept: true,
+            maxConcurrency: 1, // this should match your plan's concurrency limit 
+            reporters: [
+              'default',
+              TestDriver()
+            ],
+            setupFiles: ['testdriverai/vitest/setup'],
+          },
+        });
+        ```
+
+      </Step>
+      <Step title="Create an Example Test File">
+
+        Add your API key to the example test file below and save it as `test.mjs` in your project root.
+
+        ```js test.mjs highlight={9}
+        import { describe, expect, it } from "vitest";
+        // Import TestDriver from the vitest hooks
+        import { TestDriver } from "testdriverai/vitest/hooks";
+
+        describe("Google Search Example", () => {
+          it("should search for TestDriver", async (context) => {
+            // Create TestDriver instance - automatically connects to sandbox
+            const testdriver = TestDriver(context, {
+              apiKey: 'YOUR_API_KEY_HERE' // supply your API key here 
+            });
+
+            // Provision Chrome browser with a URL
+            // This also starts dashcam recording automatically
+            await testdriver.provision.chrome({ url: "https://duckduckgo.com" });
+
+            // Find and interact with elements using natural language
+            const searchBox = await testdriver.find("DuckDuckGo search input field");
+            await searchBox.click();
+
+            // Type into the focused element
+            await testdriver.type("testdriver.ai");
+
+            // Press Enter to search
+            await testdriver.pressKeys(["enter"]);
+
+            // Assert something is visible on the page
+            const result = await testdriver.assert("search results are displayed");
+            expect(result).toBeTruthy();
+          });
+        });
+        ```
+
+      </Step>
+      <Step title="Run Your Test">
+
+        TestDriver uses Vitest as the test runner. To run your test, use:
+        
+        ```bash
+        vitest run
+        ```
+
+        This will spawn a sandbox, launch Chrome, and run the example test!
+
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>