@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/click.mdx

@@ -1,287 +1,132 @@
 ---
 title: "click()"
 sidebarTitle: "click"
-description: "Click at specific coordinates or on elements"
+description: "Click an element you found, or click a point on the screen."
 icon: "mouse-pointer"
 ---
 
-## Element Click
-
-When you call this on an Element object, it clicks on the found element.
-
-### Syntax
+Click an element you've located with [`find()`](/find):
 
 ```javascript
-await element.click(action)
+const signInButton = await testdriver.find('Sign in button');
+await signInButton.click();
 ```
 
-### Parameters
-
-<ParamField path="action" type="string" default="click">
-  Type of click action: `'click'`, `'double-click'`, `'right-click'`, `'hover'`, `'mouseDown'`, `'mouseUp'`
-</ParamField>
-
-### Returns
-
-`Promise<void>`
-
-### Examples
+Or chain it straight onto `find()`:
 
 ```javascript
-// Regular click
-const button = await testdriver.find('submit button');
-await button.click();
-
-// Double-click
-const file = await testdriver.find('README.txt file');
-await file.click('double-click');
-
-// Right-click
-const item = await testdriver.find('menu item');
-await item.click('right-click');
-
-// Hover (same as element.hover())
-const tooltip = await testdriver.find('info icon');
-await button.click('hover');
+await testdriver.find('Sign in button').click();
 ```
 
-## Coordinate Click
+## element.click(action)
 
-Click at specific screen coordinates.
+Clicks the element at the point where `find()` located it.
 
-### Syntax
-
-```javascript
-await testdriver.click(x, y, action)
+```typescript
+element.click(action?: ClickAction): Promise<void>
 ```
 
 ### Parameters
 
-<ParamField path="x" type="number" required>
-  X coordinate
-</ParamField>
-
-<ParamField path="y" type="number" required>
-  Y coordinate
-</ParamField>
+<ParamField path="action" type="ClickAction" default="click">
+  The mouse action to perform:
 
-<ParamField path="action" type="string" default="click">
-  Type of click: `'click'`, `'double-click'`, `'right-click'`, `'mouseDown'`, `'mouseUp'`
+  - `'click'`: a left click
+  - `'double-click'`: a double click, same as [`doubleClick()`](/double-click)
+  - `'right-click'`: a right click, same as [`rightClick()`](/right-click)
+  - `'hover'`: move the mouse there without clicking, same as [`hover()`](/hover)
+  - `'mouseDown'` and `'mouseUp'`: press or release the button, for dragging. See [mouseDown()](/mouse-down).
 </ParamField>
 
-### Returns
-
-`Promise<void>`
+### Errors
 
-### Examples
+Throws an `ElementNotFoundError` if `find()` didn't locate the element. Check `found()` first when the element might not be there:
 
 ```javascript
-// Click at coordinates
-await testdriver.click(500, 300);
-
-// Double-click at coordinates
-await testdriver.click(500, 300, 'double-click');
-
-// Right-click at coordinates
-await testdriver.click(500, 300, 'right-click');
+const banner = await testdriver.find('cookie consent banner', { timeout: 0 });
+if (banner.found()) {
+  await testdriver.find('Accept all cookies button').click();
+}
 ```
 
-## Click Actions
+## testdriver.click(options)
 
-### Regular Click
+Clicks a point on the screen by its coordinates. Prefer `element.click()`, which keeps working when the layout or screen size changes.
 
-One left-click action.
-
-```javascript
-const button = await testdriver.find('Login button');
-await button.click();
+```typescript
+testdriver.click(options: { x: number; y: number; action?: ClickAction }): Promise<void>
 ```
 
-### Double Click
+### Parameters
 
-A double-click action. It usually opens files or selects text.
+<ParamField path="options" type="object" required>
+  <Expandable title="properties">
+    <ParamField path="x" type="number" required>
+      Distance from the left edge of the screen, in pixels.
+    </ParamField>
+    <ParamField path="y" type="number" required>
+      Distance from the top edge of the screen, in pixels.
+    </ParamField>
+    <ParamField path="action" type="ClickAction" default="click">
+      The mouse action, as for `element.click()`. `'hover'` doesn't move the mouse here; use [`testdriver.hover({ x, y })`](/hover) instead.
+    </ParamField>
+  </Expandable>
+</ParamField>
 
 ```javascript
-const file = await testdriver.find('document.pdf');
-await file.click('double-click');
-
-// Or use the dedicated method
-await file.doubleClick();
+await testdriver.click({ x: 640, y: 360 });
+await testdriver.click({ x: 640, y: 360, action: 'right-click' });
 ```
 
-### Right Click
+<Note>
+  The older form `testdriver.click(x, y, action)` still works. Use the options object in new tests.
+</Note>
 
-Right-click to open context menus.
+## Examples
 
-```javascript
-const folder = await testdriver.find('Documents folder');
-await folder.click('right-click');
+### Open a context menu
 
-// Or use the dedicated method
-await folder.rightClick();
+```javascript
+await testdriver.find('report.pdf in the file list').click('right-click');
+await testdriver.find('Rename in the context menu').click();
 ```
 
-### Mouse Down / Mouse Up
-
-Use these for drag operations or custom click behavior.
+### Open a file
 
 ```javascript
-const draggable = await testdriver.find('draggable item');
-await draggable.click('mouseDown');
-
-// Move to target
-const dropZone = await testdriver.find('drop zone');
-await dropZone.hover();
-await dropZone.click('mouseUp');
-
-// Or use dedicated methods
-await draggable.mouseDown();
-await dropZone.mouseUp();
+await testdriver.find('report.pdf in the file list').click('double-click');
 ```
 
-## Best Practices
-
-<Check>
-  **Prefer element clicks to coordinate clicks**
-  
-  A click on an element is more reliable. It does not depend on the resolution:
-  
-  ```javascript
-  // ✅ Preferred
-  const button = await testdriver.find('submit button');
-  await button.click();
-  
-  // ❌ Avoid (fragile)
-  await testdriver.click(500, 300);
-  ```
-</Check>
-
-<Check>
-  **Make sure that TestDriver found the element**
-  
-  ```javascript
-  const element = await testdriver.find('button');
-  if (!element.found()) {
-    throw new Error('Element not found');
-  }
-  await element.click();
-  ```
-</Check>
-
-<Warning>
-  **TestDriver must find the element before you click it**
-  
-  The `find()` method finds elements automatically. But a click on an element that TestDriver did not find throws an error:
-  
-  ```javascript
-  const element = await testdriver.find('button');
-  // This will throw if element wasn't found
-  await element.click();
-  ```
-</Warning>
-
-## Use Cases
-
-<AccordionGroup>
-  <Accordion title="Button Clicks">
-    ```javascript
-    const submitBtn = await testdriver.find('submit button');
-    await submitBtn.click();
-    
-    const cancelBtn = await testdriver.find('cancel button');
-    await cancelBtn.click();
-    ```
-  </Accordion>
-  
-  <Accordion title="Opening Files">
-    ```javascript
-    const file = await testdriver.find('report.pdf file icon');
-    await file.doubleClick();
-    ```
-  </Accordion>
-  
-  <Accordion title="Context Menus">
-    ```javascript
-    const item = await testdriver.find('file item');
-    await item.rightClick();
-    
-    // Select menu option
-    const deleteOption = await testdriver.find('Delete option');
-    await deleteOption.click();
-    ```
-  </Accordion>
-  
-  <Accordion title="Drag and Drop">
-    ```javascript
-    const source = await testdriver.find('source item');
-    await source.mouseDown();
-    
-    const target = await testdriver.find('target zone');
-    await target.hover();
-    await target.mouseUp();
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Complete Example
+### Drag an item
 
 ```javascript
-import { beforeAll, afterAll, describe, it } from 'vitest';
-import TestDriver from 'testdriverai';
+await testdriver.find('Task card titled "Write docs"').mouseDown();
+await testdriver.find('Done column').hover();
+await testdriver.find('Done column').mouseUp();
+```
 
-describe('Click Interactions', () => {
-  let testdriver;
+## Complete example
 
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
+```javascript tests/login.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
+describe('Login', () => {
+  it('shows an error for an empty form', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-  it('should perform various click actions', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Regular click
-    const loginBtn = await testdriver.find('login button');
-    await loginBtn.click();
-    
-    // Right-click for context menu
-    const profileIcon = await testdriver.find('profile icon');
-    await profileIcon.rightClick();
-    
-    const settingsOption = await testdriver.find('Settings menu option');
-    await settingsOption.click();
-    
-    // Double-click to edit
-    const nameField = await testdriver.find('name display field');
-    await nameField.doubleClick();
-    
-    // Verify state
-    await testdriver.assert('name field is now editable');
-  });
+    await testdriver.find('Sign in button below the password field').click();
 
-  it('should perform drag and drop', async () => {
-    const item = await testdriver.find('draggable item');
-    await item.mouseDown();
-    
-    // Drag to new location
-    const dropTarget = await testdriver.find('drop area');
-    await dropTarget.hover();
-    await dropTarget.mouseUp();
-    
-    // Verify
-    await testdriver.assert('item is in the drop area');
+    const result = await testdriver.assert('an error says the fields are required');
+    expect(result).toBe(true);
   });
 });
 ```
 
-## Related Methods
+## Related
 
-- [`find()`](/find) - Find elements to click
-- [`hover()`](/hover) - Put the cursor on the element without a click
-- [`doubleClick()`](/double-click) - The double-click method
-- [`rightClick()`](/right-click) - The right-click method
+- [find()](/find): locate the element to click
+- [doubleClick()](/double-click), [rightClick()](/right-click), and [hover()](/hover): shortcuts for the other actions
+- [mouseDown()](/mouse-down) and [mouseUp()](/mouse-up): drag and drop
+- [Perform actions](/performing-actions): every kind of action in one guide