@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/scroll.mdx

@@ -1,206 +1,123 @@
 ---
 title: "scroll()"
 sidebarTitle: "scroll"
-description: "Scroll pages and elements"
+description: "Scroll the page up or down with the mouse wheel."
 icon: "arrows-up-down"
 ---
 
-## Overview
+Scroll the page up or down with the mouse wheel:
 
-Scroll the page or the active element in any direction with the mouse wheel or the keyboard.
+```javascript
+await testdriver.scroll('down', { amount: 1000 });
+```
 
-<Warning>
-  **Focus Requirements**
-  
-  A scroll needs focus on the page or on a frame. If an input field or another interactive element has focus, scroll commands can fail. Before you scroll, put the focus on the page:
-  - Click a non-interactive area (for example, the page background)
-  - Push the Escape key to remove the focus from interactive elements
-  - Click outside of input fields or text areas
-  
-  **If the scroll still does not work**, use the Page Down or Page Up keys directly:
-  ```javascript
-  await testdriver.pressKeys(['pagedown']); // Scroll down
-  await testdriver.pressKeys(['pageup']);   // Scroll up
-  ```
-</Warning>
+If the page doesn't move, click somewhere on it first to give it focus.
 
-## Syntax
+## Signature
 
-```javascript
-await testdriver.scroll(direction, options)
+```typescript
+testdriver.scroll(direction?: 'up' | 'down', options?: { amount?: number }): Promise<void>
 ```
 
 ## Parameters
 
-<ParamField path="direction" type="string" default="down">
-  Direction to scroll: `'up'`, `'down'`
+<ParamField path="direction" type="'up' | 'down'" default="down">
+  Which way to scroll. `'left'` and `'right'` aren't supported: TestDriver logs an error and doesn't scroll.
 </ParamField>
 
 <ParamField path="options" type="object">
   <Expandable title="properties">
     <ParamField path="amount" type="number" default="300">
-      Amount to scroll in pixels
+      How far to scroll. Larger values scroll further.
     </ParamField>
   </Expandable>
 </ParamField>
 
-## Returns
+## Errors
 
-`Promise<void>`
+Throws an error if `direction` isn't `'up'`, `'down'`, `'left'` or `'right'`.
 
-## Examples
+If the screen doesn't change after the scroll, TestDriver logs a warning instead of throwing. This usually means the page didn't have focus.
+
+## Scroll until text appears
 
-### Basic Scrolling
+`testdriver.scrollUntilText()` scrolls in steps until it finds some text on screen:
 
 ```javascript
-// Scroll down (default)
-await testdriver.scroll();
+await testdriver.scrollUntilText({ text: 'Privacy policy' });
+await testdriver.find('Privacy policy link in the footer').click();
+```
 
-// Scroll down 5 clicks
-await testdriver.scroll('down', { amount: 5 });
+<ParamField path="options" type="object" required>
+  <Expandable title="properties">
+    <ParamField path="text" type="string" required>
+      The text to look for.
+    </ParamField>
+    <ParamField path="direction" type="'up' | 'down'" default="down">
+      Which way to scroll.
+    </ParamField>
+    <ParamField path="maxDistance" type="number" default="10000">
+      How far to scroll in total before giving up. Each step scrolls 500.
+    </ParamField>
+    <ParamField path="invert" type="boolean" default="false">
+      Scroll until the text is no longer on screen.
+    </ParamField>
+  </Expandable>
+</ParamField>
 
-// Scroll up
-await testdriver.scroll('up');
+It throws an error if the text doesn't appear within `maxDistance`. `testdriver.scrollUntilImage({ description })` works the same way for an image you describe.
 
-// Scroll up 2 clicks
-await testdriver.scroll('up', { amount: 2 });
-```
+## Examples
 
-### Horizontal Scrolling
+### Focus the page, then scroll
 
 ```javascript
-// Scroll right
-await testdriver.scroll('right', { amount: 3 });
-
-// Scroll left
-await testdriver.scroll('left', { amount: 3 });
+await testdriver.find('the page heading').click();
+await testdriver.scroll('down', { amount: 1000 });
 ```
 
-### Scroll Methods
+### Load more results in an infinite list
 
 ```javascript
-// Mouse wheel scroll (default)
-await testdriver.scroll('down', { amount: 3 });
-
-// For keyboard-based scrolling, use pressKeys instead
-await testdriver.pressKeys(['pagedown']);
+for (let i = 0; i < 3; i++) {
+  await testdriver.scroll('down', { amount: 1000 });
+}
+await testdriver.assert('more than 20 results are listed');
 ```
 
-## Best Practices
-
-<Check>
-  **Make sure that the page has focus before you scroll**
-  
-  ```javascript
-  // After typing in an input, unfocus it first
-  await testdriver.find('email input').click();
-  await testdriver.type('user@example.com');
-  
-  // Click elsewhere or press Escape before scrolling
-  await testdriver.pressKeys(['escape']);
-  // Or click a non-interactive area
-  // await testdriver.find('page background').click();
-  
-  // Now scroll will work properly
-  await testdriver.scroll('down');
-  
-  // If scroll still doesn't work, use Page Down directly
-  // await testdriver.pressKeys(['pagedown']);
-  ```
-</Check>
-
-<Check>
-  **Control the scroll distance with the options object**
-  
-  ```javascript
-  // For web pages, mouse scroll works well
-  await testdriver.scroll('down', { amount: 3 });
-  
-  // For desktop apps or when mouse doesn't work, use keyboard
-  await testdriver.pressKeys(['pagedown']);
-  ```
-</Check>
-
-<Warning>
-  **The keyboard scroll uses Page Down and Page Up**
-  
-  A keyboard scroll usually moves one "page" each time. This can be more than the click amount that you set. It is more compatible than a mouse scroll, but it is less precise.
-</Warning>
-
-## Use Cases
-
-<AccordionGroup>
-  <Accordion title="Infinite Scroll">
-    ```javascript
-    // Scroll multiple times for infinite scroll
-    for (let i = 0; i < 5; i++) {
-      await testdriver.scroll('down', { amount: 5 });
-      await new Promise(r => setTimeout(r, 1000)); // Wait for load
-    }
-    ```
-  </Accordion>
-  
-  <Accordion title="Horizontal Gallery">
-    ```javascript
-    // Navigate horizontal carousel
-    await testdriver.scroll('right', { amount: 3 });
-    await new Promise(r => setTimeout(r, 500));
-    
-    const nextImage = await testdriver.find('next image in carousel');
-    await nextImage.click();
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Complete Example
+### Use the keyboard instead
+
+Some apps don't respond to the mouse wheel. Press Page Down with [`pressKeys()`](/press-keys):
 
 ```javascript
-import { beforeAll, afterAll, describe, it } from 'vitest';
-import TestDriver from 'testdriverai';
+await testdriver.pressKeys(['pagedown']);
+```
 
-describe('Scrolling', () => {
-  let testdriver;
+## Complete example
 
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
+```javascript tests/scroll.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
+describe('Scroll', () => {
+  it('scrolls the heading out of view', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://www.webhamster.com/' });
 
-  it('should scroll to find elements', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Scroll down the page
-    await testdriver.scroll('down', { amount: 5 });
-    
-    // Click footer link
-    const privacyLink = await testdriver.find('Privacy Policy link');
-    await privacyLink.click();
-    
-    await testdriver.assert('privacy policy page is displayed');
-  });
+    // Click the page so it has focus before scrolling
+    await testdriver.find('The Hamster Dance, large heading at the top of the page').click();
+    await testdriver.scroll('down', { amount: 1000 });
 
-  it('should handle infinite scroll', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Scroll multiple times to load content
-    for (let i = 0; i < 3; i++) {
-      await testdriver.scroll('down', { amount: 5 });
-      await new Promise(r => setTimeout(r, 1500)); // Wait for load
-    }
-    
-    // Verify content loaded
-    await testdriver.assert('more than 10 items are visible');
+    const result = await testdriver.assert(
+      "the text 'The Hamster Dance' isn't visible in the page content",
+    );
+    expect(result).toBe(true);
   });
 });
 ```
 
-## Related Methods
+## Related
 
-- [`find()`](/find) - Find elements after a scroll
-- [`pressKeys()`](/press-keys) - Use the Page Down and Page Up keys
-- [`wait()`](/wait) - Wait after a scroll
+- [pressKeys()](/press-keys): scroll with Page Down, Home and End
+- [find()](/find): locate an element after scrolling to it
+- [Perform actions](/performing-actions): every kind of action in one guide

package/docs/secrets.mdx

@@ -1,115 +1,120 @@
 ---
-title: "Using Secrets"
-description: "Securely manage passwords and sensitive data in your tests"
+title: "Use secrets"
+sidebarTitle: "Using secrets"
+description: "Keep passwords and tokens out of your test code and TestDriver's logs."
 icon: "key"
 ---
 
-Protect sensitive information such as passwords, API keys, and tokens in your TestDriver tests.
+Store credentials outside your code, and mark them as secret when you type them.
 
-## Typing Secrets Securely
+- Read passwords and tokens from environment variables, never from the test file.
+- Type them with `secret: true` so TestDriver doesn't log or store them.
 
-When you type sensitive information such as passwords, use the `secret: true` option. This stops TestDriver from a log or a store of the value:
+## Type a secret
 
-```javascript
-import { test } from 'vitest';
-import { chrome } from 'testdriverai/presets';
+Pass `{ secret: true }` to [`type()`](/type) for any sensitive value. Click the field first, then type:
 
-test('login with secure password', async (context) => {
-  const { testdriver } = await chrome(context, { 
-    url: 'https://myapp.com/login' 
-  });
+```javascript tests/login.test.mjs
+import { expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-  await testdriver.find('email input').click();
-  await testdriver.type(process.env.TD_USERNAME);
-  
-  await testdriver.find('password input').click();
-  // Password is masked in logs and recordings
-  await testdriver.type(process.env.TD_PASSWORD, { secret: true });
-  
-  await testdriver.find('login button').click();
-  await testdriver.assert('dashboard is visible');
+it('signs in', async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: `${process.env.APP_URL}/login` });
+
+  const usernameField = await testdriver.find('Username input field');
+  await usernameField.click();
+  await testdriver.type(process.env.TEST_USERNAME);
+
+  const passwordField = await testdriver.find('Password input field');
+  await passwordField.click();
+  await testdriver.type(process.env.TEST_PASSWORD, { secret: true });
+
+  const signInButton = await testdriver.find('Sign in button below the password field');
+  await signInButton.click();
+
+  const result = await testdriver.assert('the dashboard is visible');
+  expect(result).toBe(true);
 });
 ```
 
-<Note>
-When you set `secret: true`, the typed text shows as `****` in all logs, recordings, and dashcam output.
-</Note>
+## What `secret: true` hides
 
-## Storing Secrets in GitHub
+With `secret: true`, TestDriver replaces the text with `****`:
 
-Store sensitive credentials as GitHub repository secrets. Then they are never in your code:
+- In the SDK's console output.
+- In the record of the action that TestDriver stores for the test run.
 
-<Steps>
-  <Step title="Navigate to Repository Settings">
-    Go to your GitHub repository → **Settings** → **Secrets and variables** → **Actions**
-  </Step>
-  <Step title="Add Repository Secrets">
-    Click **New repository secret** and add your secrets:
-    - `TD_API_KEY` - Your TestDriver API key
-    - `TD_USERNAME` - Test account username
-    - `TD_PASSWORD` - Test account password
-  </Step>
-  <Step title="Use in GitHub Actions">
-    Reference secrets in your workflow file:
-    ```yaml .github/workflows/test.yml
-    - name: Run TestDriver tests
-      env:
-        TD_API_KEY: ${{ secrets.TD_API_KEY }}
-        TD_USERNAME: ${{ secrets.TD_USERNAME }}
-        TD_PASSWORD: ${{ secrets.TD_PASSWORD }}
-      run: vitest run
-    ```
-  </Step>
-</Steps>
+The text is still typed into the sandbox, so `secret: true` can't hide what the screen shows. If the field displays its contents, the value appears in the [Dashcam](/dashcam) recording and in screenshots. Password fields usually mask what you type, but plain text fields don't.
+
+<Warning>
+  With [`autoScreenshots`](/options#param-auto-screenshots) on, screenshot file names include the first characters of the typed text, even when `secret` is `true`. Leave `autoScreenshots` off in tests that type secrets.
+</Warning>
 
-## Local Development
+## Store secrets locally
 
-For local development, store secrets in a `.env` file:
+TestDriver loads a `.env` file in your project root automatically. Put your local credentials there:
 
 ```bash .env
-TD_API_KEY=your_api_key_here
-TD_USERNAME=testuser@example.com
-TD_PASSWORD=your_secure_password
+TD_API_KEY=your_api_key
+APP_URL=https://staging.example.com
+TEST_USERNAME=qa@example.com
+TEST_PASSWORD=your_test_password
 ```
 
-<Warning>
-Never commit `.env` files to version control. Add `.env` to your `.gitignore` file.
-</Warning>
+Add `.env` to `.gitignore` so it's never committed:
 
-## Complete Example
-
-Here's a full login test with proper secrets handling:
-
-```javascript tests/login.test.js
-import { test, expect } from 'vitest';
-import { chrome } from 'testdriverai/presets';
-
-test('secure login flow', async (context) => {
-  const { testdriver } = await chrome(context, { 
-    url: process.env.TD_WEBSITE || 'https://staging.myapp.com'
-  });
-
-  // Enter username (not sensitive)
-  await testdriver.find('email input').click();
-  await testdriver.type(process.env.TD_USERNAME);
-  
-  // Enter password securely
-  await testdriver.find('password input').click();
-  await testdriver.type(process.env.TD_PASSWORD, { secret: true });
-  
-  // Submit login
-  await testdriver.find('login button').click();
-  
-  // Verify successful login
-  const loggedIn = await testdriver.assert('user is logged in');
-  expect(loggedIn).toBeTruthy();
-});
+```bash .gitignore
+.env
 ```
 
-<Card title="Secrets Best Practices" icon="shield-check">
-  - **Always use `secret: true`** when typing passwords, tokens, or sensitive data
-  - **Use environment variables** to keep secrets out of code
-  - **Store secrets in your CI provider** (GitHub Actions, GitLab CI, etc.)
-  - **Never commit secrets** to version control
-  - **Rotate secrets regularly** to maintain security
-</Card>
+## Store secrets in CI
+
+In GitHub Actions, store each credential as a repository secret:
+
+<Steps>
+  <Step title="Open your repository's secrets">
+    In GitHub, go to **Settings** > **Secrets and variables** > **Actions**.
+  </Step>
+  <Step title="Add each secret">
+    Click **New repository secret** and add `TEST_USERNAME` and `TEST_PASSWORD`.
+  </Step>
+  <Step title="Pass them to the test step">
+    Map the secrets to environment variables in your workflow:
+
+    ```yaml .github/workflows/testdriver.yml
+    - name: Run TestDriver tests
+      run: npx vitest run
+      env:
+        APP_URL: https://staging.example.com
+        TEST_USERNAME: ${{ secrets.TEST_USERNAME }}
+        TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+    ```
+  </Step>
+</Steps>
+
+You don't need to store your TestDriver API key this way. The `testdriverai/action` step authenticates with GitHub OIDC. See [Run in CI/CD](/ci-cd) for the full workflow.
+
+## Checklist
+
+- Type passwords, tokens, and other sensitive values with `secret: true`.
+- Read credentials from environment variables, not from the test file.
+- Keep `.env` out of version control.
+- Use test accounts with only the access your tests need.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Use variables and test data" icon="square-root-variable" href="/variables">
+    Drive tests with environment variables and fixtures.
+  </Card>
+  <Card title="type()" icon="keyboard" href="/type">
+    Every option for typing text.
+  </Card>
+  <Card title="Run in CI/CD" icon="code-branch" href="/ci-cd">
+    Authenticate and run tests in your pipeline.
+  </Card>
+  <Card title="Reuse code" icon="recycle" href="/reusable-code">
+    Put your login steps in a shared helper.
+  </Card>
+</CardGroup>