@testdriverai/agent 7.11.229-canary → 7.11.232-test

package/docs/reusable-code.mdx

@@ -1,249 +1,146 @@
 ---
-title: "Reusable Code Snippets"
-description: "Build maintainable test suites with reusable code patterns"
+title: "Reuse code across tests"
+sidebarTitle: "Reusable code snippets"
+description: "Share login steps and other common flows between tests with helpers and page objects."
 icon: "recycle"
 ---
 
-When your test suite becomes larger, put the common patterns into reusable code. This keeps the tests short, easy to read, and easy to keep.
-
-## Helper Functions
-
-The most simple method is to put the common actions into helper functions. Make a `helpers/` directory for the shared utilities:
-
-```javascript test/helpers/auth.js
-export async function login(testdriver, { email, password }) {
-  const emailInput = await testdriver.find('email input');
-  await emailInput.click();
-  await testdriver.type(email);
-  
-  const passwordInput = await testdriver.find('password input');
-  await passwordInput.click();
-  await testdriver.type(password);
-  
-  const loginButton = await testdriver.find('login button');
-  await loginButton.click();
-  
-  const result = await testdriver.assert('user is logged in');
-  return result;
-}
+When several tests repeat the same steps, move those steps into shared code.
 
-export async function logout(testdriver) {
-  const userMenu = await testdriver.find('user menu');
-  await userMenu.click();
-  
-  const logoutButton = await testdriver.find('logout button');
-  await logoutButton.click();
-}
-```
+- **Helper functions** wrap one flow, such as signing in.
+- **Page objects** group every action for one screen in a class.
+
+Both are plain JavaScript modules. They take the `testdriver` client as an argument, so they work in any test.
 
-<Warning>
-**Do not put dynamic values in element descriptions.** An element selector must describe the *type* of the element. It must not describe specific content that can change.
+## Write a helper function
 
-**❌ Bad:** `await testdriver.find('profile name TestDriver in the top right')`  
-**✅ Good:** `await testdriver.find('user profile name in the top right')`
+Put the shared steps in a function that takes the client. This helper signs in to the TestDriver demo store:
 
-Hardcoded values like usernames, product names, or prices will cause tests to fail when the data changes. Use generic descriptions that work regardless of the specific content displayed.
-</Warning>
+```javascript tests/helpers/auth.js
+export async function signIn(testdriver, username = 'standard_user') {
+  const usernameField = await testdriver.find('Username input field');
+  await usernameField.click();
+  await testdriver.type(username);
 
-Now import and use these helpers in any test:
+  // The demo store shows its password on the login page
+  const password = await testdriver.extract('the password shown on the login page');
 
-```javascript test/checkout.test.mjs
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-import { login } from './helpers/auth.js';
+  const passwordField = await testdriver.find('Password input field');
+  await passwordField.click();
+  await testdriver.type(password, { secret: true });
+
+  const signInButton = await testdriver.find('Sign in button below the password field');
+  await signInButton.click();
+}
+```
 
-describe("Checkout", () => {
-  it("should complete checkout as logged in user", async (context) => {
-    const testdriver = TestDriver(context);
-    
-    await testdriver.provision.chrome({
-      url: 'https://shop.example.com',
-    });
+Import it and call it with your test's client:
 
-    // Use the helper
-    await login(testdriver, { 
-      email: 'user@example.com', 
-      password: 'password123' 
-    });
+```javascript tests/cart.test.mjs
+import { expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+import { signIn } from './helpers/auth.js';
 
-    // Continue with checkout steps...
-    const cartButton = await testdriver.find('cart button');
-    await cartButton.click();
-  });
+it('shows an empty cart after signing in', async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
+
+  await signIn(testdriver);
+
+  const cartIcon = await testdriver.find('Shopping cart icon in the top right corner');
+  await cartIcon.click();
+
+  const result = await testdriver.assert('the cart is empty');
+  expect(result).toBe(true);
 });
 ```
 
-## Page Objects
+Pass values that change between tests, like the username, as arguments. Keep them out of the descriptions you pass to [`find()`](/find), so the [cache](/caching) can match them on every run.
 
-For larger test suites, the Page Object pattern encapsulates all interactions with a specific page or component:
+## Group actions with a page object
 
-```javascript test/pages/LoginPage.js
+A page object is a class with one method per action on a screen. Use one when many tests work with the same screen.
+
+```javascript tests/pages/login-page.js
 export class LoginPage {
   constructor(testdriver) {
-    this.td = testdriver;
+    this.testdriver = testdriver;
   }
 
-  async enterEmail(email) {
-    const input = await this.td.find('email input');
-    await input.click();
-    await this.td.type(email);
+  async enterUsername(username) {
+    const usernameField = await this.testdriver.find('Username input field');
+    await usernameField.click();
+    await this.testdriver.type(username);
   }
 
   async enterPassword(password) {
-    const input = await this.td.find('password input');
-    await input.click();
-    await this.td.type(password);
+    const passwordField = await this.testdriver.find('Password input field');
+    await passwordField.click();
+    await this.testdriver.type(password, { secret: true });
   }
 
   async submit() {
-    const button = await this.td.find('submit button');
-    await button.click();
+    const signInButton = await this.testdriver.find('Sign in button below the password field');
+    await signInButton.click();
   }
+}
+```
 
-  async login(email, password) {
-    await this.enterEmail(email);
-    await this.enterPassword(password);
-    await this.submit();
-  }
+```javascript tests/login.test.mjs
+import { expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+import { LoginPage } from './pages/login-page.js';
 
-  async assertError(message) {
-    return await this.td.assert(`error message shows "${message}"`);
-  }
+it('asks for a password when it is missing', async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-  async assertLoggedIn() {
-    return await this.td.assert('user dashboard is visible');
-  }
-}
-```
+  const loginPage = new LoginPage(testdriver);
+  await loginPage.enterUsername('standard_user');
+  await loginPage.submit();
 
-Use the page object in your tests:
-
-```javascript test/auth.test.mjs
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-import { LoginPage } from './pages/LoginPage.js';
-
-describe("Authentication", () => {
-  it("should show error for invalid credentials", async (context) => {
-    const testdriver = TestDriver(context);
-    
-    await testdriver.provision.chrome({
-      url: 'https://app.example.com/login',
-    });
-
-    const loginPage = new LoginPage(testdriver);
-    
-    await loginPage.login('invalid@test.com', 'wrongpassword');
-    
-    const hasError = await loginPage.assertError('Invalid credentials');
-    expect(hasError).toBeTruthy();
-  });
-
-  it("should redirect to dashboard on success", async (context) => {
-    const testdriver = TestDriver(context);
-    
-    await testdriver.provision.chrome({
-      url: 'https://app.example.com/login',
-    });
-
-    const loginPage = new LoginPage(testdriver);
-    
-    await loginPage.login('valid@test.com', 'correctpassword');
-    
-    const isLoggedIn = await loginPage.assertLoggedIn();
-    expect(isLoggedIn).toBeTruthy();
-  });
+  const result = await testdriver.assert('a "Please fill out this field" message is visible near the password field');
+  expect(result).toBe(true);
 });
 ```
 
-## Shared Test Fixtures
-
-Create reusable fixtures for common test setup scenarios:
-
-```javascript test/fixtures/index.js
-export const testUsers = {
-  admin: { email: 'admin@example.com', password: 'admin123' },
-  regular: { email: 'user@example.com', password: 'user123' },
-  guest: { email: 'guest@example.com', password: 'guest123' },
-};
-
-export const testUrls = {
-  staging: 'https://staging.example.com',
-  production: 'https://example.com',
-};
-
-export async function setupAuthenticatedSession(testdriver, user = testUsers.regular) {
-  const emailInput = await testdriver.find('email input');
-  await emailInput.click();
-  await testdriver.type(user.email);
-  
-  const passwordInput = await testdriver.find('password input');
-  await passwordInput.click();
-  await testdriver.type(user.password);
-  
-  const loginButton = await testdriver.find('login button');
-  await loginButton.click();
-  
-  await testdriver.assert('user is logged in');
-}
-```
+Start with helper functions. Move to page objects when several tests repeat the same actions on one screen.
 
-```javascript test/admin.test.mjs
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-import { testUsers, testUrls, setupAuthenticatedSession } from './fixtures/index.js';
-
-describe("Admin Panel", () => {
-  it("should access admin settings", async (context) => {
-    const testdriver = TestDriver(context);
-    
-    await testdriver.provision.chrome({
-      url: `${testUrls.staging}/login`,
-    });
-
-    await setupAuthenticatedSession(testdriver, testUsers.admin);
-
-    const settingsLink = await testdriver.find('admin settings link');
-    await settingsLink.click();
-    
-    const result = await testdriver.assert('admin settings panel is visible');
-    expect(result).toBeTruthy();
-  });
-});
-```
+## Organize your files
 
-## Suggested Project Structure
+A layout that keeps shared code apart from tests:
 
 <FileTree>
-  <Folder name="test" defaultOpen>
-    <Folder name="fixtures" defaultOpen>
-      <File name="index.js" />
-    </Folder>
+  <Folder name="tests" defaultOpen>
     <Folder name="helpers" defaultOpen>
       <File name="auth.js" />
-      <File name="navigation.js" />
-      <File name="forms.js" />
     </Folder>
     <Folder name="pages" defaultOpen>
-      <File name="LoginPage.js" />
-      <File name="DashboardPage.js" />
-      <File name="CheckoutPage.js" />
+      <File name="login-page.js" />
     </Folder>
-    <Folder name="specs" defaultOpen>
-      <File name="auth.test.mjs" />
-      <File name="checkout.test.mjs" />
-      <File name="search.test.mjs" />
+    <Folder name="fixtures" defaultOpen>
+      <File name="usernames.js" />
     </Folder>
+    <File name="cart.test.mjs" />
+    <File name="login.test.mjs" />
   </Folder>
 </FileTree>
 
-| Folder | Purpose |
-|--------|---------|
-| `fixtures/` | Test data and setup utilities |
-| `helpers/` | Reusable helper functions |
-| `pages/` | Page object classes |
-| `specs/` | Test files |
-
-<Tip>
-Start simple with helper functions. Only introduce page objects when you find yourself duplicating the same element interactions across multiple tests.
-</Tip>
+By default, Vitest runs only files named `*.test.*` or `*.spec.*`, so helpers, page objects, and [fixtures](/variables#reuse-test-data-with-fixtures) aren't run as tests.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Use variables and test data" icon="square-root-variable" href="/variables">
+    Feed helpers with environment variables and fixtures.
+  </Card>
+  <Card title="Use secrets" icon="key" href="/secrets">
+    Keep the credentials your helpers type out of logs.
+  </Card>
+  <Card title="Locate elements" icon="crosshairs" href="/locating-elements">
+    Write descriptions that find the right element.
+  </Card>
+  <Card title="Click an icon example" icon="mouse-pointer" href="/examples/click-icon">
+    A complete test that uses a login helper.
+  </Card>
+</CardGroup>

package/docs/right-click.mdx

@@ -1,123 +1,81 @@
 ---
-title: "rightClick"
-description: "Perform a right-click action to open context menus"
+title: "rightClick()"
+sidebarTitle: "rightClick"
+description: "Right-click an element you found, usually to open a context menu."
 icon: "bars"
 ---
 
-## Overview
-
-The `rightClick()` method does a right-click action on an element. It usually opens context menus. You can call it on an [`Element`](/core-concepts/elements) instance. Or you can use it with a selector.
-
-## Syntax
+Right-click an element you've located with [`find()`](/find), then pick an item from the menu that opens:
 
 ```javascript
-// Right-click on an element
-await element.rightClick();
-
-// Right-click using a selector
-await ai.rightClick('selector');
+await testdriver.find('report.pdf in the file list').rightClick();
+await testdriver.find('Rename in the context menu').click();
 ```
 
-## Parameters
+## element.rightClick()
 
-When called on an `Element`, no parameters are required.
+Right-clicks the element at the point where `find()` located it. It's the same as `element.click('right-click')`.
 
-When called directly on the AI client:
+```typescript
+element.rightClick(): Promise<void>
+```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `selector` | `string` | The selector describing the element to right-click |
+It takes no parameters.
 
-## Returns
+### Errors
 
-It returns a `Promise<void>`. The promise resolves when the right-click action completes.
+Throws an `ElementNotFoundError` if `find()` didn't locate the element. See [click()](/click#errors) for how to check `found()` first.
 
-## Examples
+## Right-click at coordinates
 
-### Right-Click to Open Context Menu
+The client has no `rightClick()` method. To right-click a point on the screen, pass `action: 'right-click'` to [`testdriver.click()`](/click#testdriver-click-options):
 
 ```javascript
-const fileItem = await ai.find('README.md file');
-await fileItem.rightClick();
-
-// Select menu option
-await ai.click('Delete from context menu');
+await testdriver.click({ x: 640, y: 360, action: 'right-click' });
 ```
 
-### Direct Right-Click with Selector
+Prefer `element.rightClick()`, which keeps working when the layout or screen size changes.
 
-```javascript
-await ai.rightClick('image in the gallery');
-await ai.click('Save image as');
-```
+## Examples
 
-### VS Code Context Menu
+### Open a link in a new tab
 
 ```javascript
-import { test } from 'vitest';
-import { vscode } from '@testdriver/sdk';
-
-test('renames a file via context menu', async () => {
-  const { ai } = await vscode();
-  
-  // Right-click on a file
-  await ai.rightClick('test.js in the file explorer');
-  
-  // Click rename option
-  await ai.click('Rename');
-  
-  // Type new name
-  await ai.type('test.spec.js');
-  await ai.pressKeys('Enter');
-  
-  // Verify rename
-  const renamedFile = await ai.find('test.spec.js in the file explorer');
-  expect(renamedFile).toBeTruthy();
-});
+await testdriver.find('Documentation link in the page footer').rightClick();
+await testdriver.find('Open link in new tab in the context menu').click();
 ```
 
-### Browser Context Menu
+### Rename a file in VS Code
 
 ```javascript
-import { test } from 'vitest';
-import { chrome } from '@testdriver/sdk';
-
-test('opens link in new tab', async () => {
-  const { ai } = await chrome('https://example.com');
-  
-  // Right-click on a link
-  await ai.rightClick('Documentation link');
-  
-  // Select "Open in new tab"
-  await ai.click('Open link in new tab');
-});
+await testdriver.find('index.js in the Explorer sidebar').rightClick();
+await testdriver.find('Rename in the context menu').click();
+await testdriver.type('main.js');
+await testdriver.pressKeys(['enter']);
 ```
 
-### Custom Context Menu in Web App
+## Complete example
 
-```javascript
-test('uses custom context menu', async () => {
-  const { ai } = await chrome('https://app.example.com');
-  
-  // Right-click on custom element
-  await ai.rightClick('project item in the list');
-  
-  // Wait for custom menu to appear
-  await ai.find('custom context menu');
-  
-  // Click menu option
-  await ai.click('Duplicate project');
-  
-  // Verify duplication
-  const duplicatedProject = await ai.find('project item (copy)');
-  expect(duplicatedProject).toBeTruthy();
+```javascript tests/context-menu.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+describe('Context menu', () => {
+  it('opens the browser context menu on the page', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
+
+    await testdriver.find('the page heading').rightClick();
+
+    const result = await testdriver.assert('a context menu with a "Back" item is open');
+    expect(result).toBe(true);
+  });
 });
 ```
 
-## Related Methods
+## Related
 
-- [`click()`](/click) - Single click on an element
-- [`doubleClick()`](/double-click) - Double-click on an element
-- [`mouseDown()`](/mouse-down) - Press mouse button without releasing
-- [`mouseUp()`](/mouse-up) - Release mouse button
-- [`hover()`](/hover) - Move mouse over element without clicking
+- [click()](/click): single clicks, and clicks at coordinates
+- [doubleClick()](/double-click): open files and select words
+- [find()](/find): locate the element to right-click
+- [Perform actions](/performing-actions): every kind of action in one guide