@testdriverai/mcp 7.11.136-test → 7.11.138-test
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ai/skills/testdriver-assert/SKILL.md +5 -5
- package/ai/skills/testdriver-caching/SKILL.md +2 -2
- package/ai/skills/testdriver-changelog/SKILL.md +186 -0
- package/ai/skills/testdriver-claude-mcp-plugin/SKILL.md +208 -0
- package/ai/skills/testdriver-click/SKILL.md +13 -13
- package/ai/skills/testdriver-client/SKILL.md +1 -1
- package/ai/skills/testdriver-debugging-with-screenshots/SKILL.md +5 -5
- package/ai/skills/testdriver-double-click/SKILL.md +7 -7
- package/ai/skills/testdriver-enterprise/SKILL.md +1 -1
- package/ai/skills/testdriver-events/SKILL.md +1 -1
- package/ai/skills/testdriver-exec/SKILL.md +10 -10
- package/ai/skills/testdriver-extract/SKILL.md +6 -6
- package/ai/skills/testdriver-find/SKILL.md +61 -61
- package/ai/skills/testdriver-focus-application/SKILL.md +6 -6
- package/ai/skills/testdriver-generating-tests/SKILL.md +3 -3
- package/ai/skills/testdriver-hosted/SKILL.md +3 -3
- package/ai/skills/testdriver-hover/SKILL.md +6 -6
- package/ai/skills/testdriver-making-assertions/SKILL.md +2 -2
- package/ai/skills/testdriver-mouse-down/SKILL.md +9 -9
- package/ai/skills/testdriver-mouse-up/SKILL.md +9 -9
- package/ai/skills/testdriver-parse/SKILL.md +4 -4
- package/ai/skills/testdriver-performing-actions/SKILL.md +4 -4
- package/ai/skills/testdriver-press-keys/SKILL.md +5 -5
- package/ai/skills/testdriver-quickstart/SKILL.md +51 -54
- package/ai/skills/testdriver-redraw/SKILL.md +1 -1
- package/ai/skills/testdriver-right-click/SKILL.md +7 -7
- package/ai/skills/testdriver-screenshot/SKILL.md +9 -9
- package/ai/skills/testdriver-scroll/SKILL.md +13 -13
- package/ai/skills/testdriver-self-hosted/SKILL.md +1 -1
- package/ai/skills/testdriver-type/SKILL.md +7 -7
- package/ai/skills/testdriver-wait/SKILL.md +5 -5
- package/ai/skills/testdriver-what-is-testdriver/SKILL.md +11 -11
- package/docs/{v7/_drafts → _drafts}/agents.mdx +1 -1
- package/docs/{v7/_drafts → _drafts}/best-practices.mdx +4 -4
- package/docs/{v7/_drafts → _drafts}/caching-selectors.mdx +3 -3
- package/docs/{v7/_drafts → _drafts}/configuration.mdx +4 -4
- package/docs/{v7/_drafts → _drafts}/debugging.mdx +4 -4
- package/docs/{v7/_drafts → _drafts}/error-handling.mdx +4 -4
- package/docs/{v7/_drafts → _drafts}/faq.mdx +7 -7
- package/docs/{v7/_drafts → _drafts}/installation.mdx +2 -2
- package/docs/{v7/_drafts → _drafts}/migration.mdx +4 -4
- package/docs/{v7/_drafts → _drafts}/observable.mdx +3 -3
- package/docs/{v7/_drafts → _drafts}/powerful.mdx +4 -4
- package/docs/{v7/_drafts → _drafts}/readme.mdx +11 -11
- package/docs/{v7/_drafts → _drafts}/reports.mdx +4 -4
- package/docs/{v7/_drafts → _drafts}/scalable.mdx +10 -10
- package/docs/{v7/_drafts → _drafts}/troubleshooting.mdx +4 -4
- package/docs/{v7/_drafts → _drafts}/vitest-plugin.mdx +2 -2
- package/docs/{v7/_drafts → _drafts}/vitest.mdx +9 -9
- package/docs/_scripts/generate-examples.js +9 -10
- package/docs/_scripts/generate-skills.js +4 -4
- package/docs/{v7/agent.mdx → agent.mdx} +17 -17
- package/docs/{v7/assert.mdx → assert.mdx} +5 -5
- package/docs/{v7/aws-setup.mdx → aws-setup.mdx} +6 -6
- package/docs/{v7/cache.mdx → cache.mdx} +9 -9
- package/docs/{v7/caching.mdx → caching.mdx} +13 -12
- package/docs/{v7/captcha.mdx → captcha.mdx} +7 -7
- package/docs/changelog.mdx +13 -13
- package/docs/{v7/ci-cd.mdx → ci-cd.mdx} +10 -10
- package/docs/{v7/click.mdx → click.mdx} +13 -13
- package/docs/client.mdx +323 -0
- package/docs/{v7/copilot → copilot}/auto-healing.mdx +2 -2
- package/docs/{v7/copilot → copilot}/running-tests.mdx +8 -8
- package/docs/{v7/customizing-devices.mdx → customizing-devices.mdx} +1 -1
- package/docs/{v7/dashcam.mdx → dashcam.mdx} +3 -3
- package/docs/{v7/debugging-with-screenshots.mdx → debugging-with-screenshots.mdx} +12 -12
- package/docs/docs.json +429 -288
- package/docs/{v7/double-click.mdx → double-click.mdx} +7 -7
- package/docs/{v7/elements.mdx → elements.mdx} +7 -7
- package/docs/{v7/enterprise.mdx → enterprise.mdx} +2 -2
- package/docs/{v7/errors.mdx → errors.mdx} +3 -3
- package/docs/{v7/events.mdx → events.mdx} +4 -4
- package/docs/{v7/exec.mdx → exec.mdx} +10 -10
- package/docs/{v7/extract.mdx → extract.mdx} +10 -10
- package/docs/{v7/find.mdx → find.mdx} +61 -61
- package/docs/{v7/focus-application.mdx → focus-application.mdx} +6 -6
- package/docs/{v7/generating-tests.mdx → generating-tests.mdx} +10 -10
- package/docs/guide/best-practices-polling.mdx +6 -1
- package/docs/{v7/hosted.mdx → hosted.mdx} +7 -7
- package/docs/{v7/hover.mdx → hover.mdx} +6 -6
- package/docs/interacting-with-your-app.mdx +198 -0
- package/docs/locating-elements.mdx +423 -0
- package/docs/{v7/making-assertions.mdx → making-assertions.mdx} +7 -7
- package/docs/{v7/mouse-down.mdx → mouse-down.mdx} +9 -9
- package/docs/{v7/mouse-up.mdx → mouse-up.mdx} +9 -9
- package/docs/options.mdx +320 -0
- package/docs/{v7/parse.mdx → parse.mdx} +12 -12
- package/docs/{v7/performing-actions.mdx → performing-actions.mdx} +11 -11
- package/docs/{v7/press-keys.mdx → press-keys.mdx} +5 -5
- package/docs/{v7/provision.mdx → provision.mdx} +9 -9
- package/docs/quickstart-cli.mdx +437 -0
- package/docs/quickstart-github.mdx +54 -0
- package/docs/quickstart-manual.mdx +135 -0
- package/docs/quickstart.mdx +22 -0
- package/docs/{v7/redraw.mdx → redraw.mdx} +7 -7
- package/docs/{v7/reusable-code.mdx → reusable-code.mdx} +3 -3
- package/docs/{v7/right-click.mdx → right-click.mdx} +7 -7
- package/docs/{v7/screenshot.mdx → screenshot.mdx} +9 -9
- package/docs/{v7/screenshots.mdx → screenshots.mdx} +3 -3
- package/docs/{v7/scroll.mdx → scroll.mdx} +13 -13
- package/docs/{v7/secrets.mdx → secrets.mdx} +4 -4
- package/docs/{v7/self-hosted.mdx → self-hosted.mdx} +7 -7
- package/docs/{v7/test-results-json.mdx → test-results-json.mdx} +4 -4
- package/docs/{v7/type.mdx → type.mdx} +7 -7
- package/docs/{v7/variables.mdx → variables.mdx} +2 -2
- package/docs/{v7/wait.mdx → wait.mdx} +5 -5
- package/docs/what-is-testdriver.mdx +54 -0
- package/lib/environments.json +1 -1
- package/lib/github-comment.mjs +2 -3
- package/package.json +1 -1
- package/scripts/generate-skills.js +1 -1
- package/docs/v7/client.mdx +0 -486
- package/docs/v7/quickstart.mdx +0 -451
- package/docs/v7/what-is-testdriver.mdx +0 -54
- /package/docs/{v7/_drafts → _drafts}/architecture.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/auto-cache-key.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/awesome-logs-quick-ref.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/cli-to-sdk-migration.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/assert.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/exec.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/focus-application.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/hover-image.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/hover-text.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/if.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/match-image.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/press-keys.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/remember.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/run.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/scroll-until-image.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/scroll-until-text.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/scroll.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/type.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/wait-for-image.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/wait-for-text.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/commands/wait.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/contributing.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/dashcam-title-feature.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/hooks.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/init-command.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/playwright.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/plugin-migration.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/presets.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/progressive-disclosure.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/provision.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/quick-start-test-recording.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/screenshot.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/sdk-awesome-logs.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/sdk-browser-rendering.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/sdk-migration.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/sdk-v7-complete.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/self-hosting.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/test-recording.mdx +0 -0
- /package/docs/{v7/_drafts → _drafts}/writing-tests.mdx +0 -0
- /package/docs/{v7/examples → examples}/ai.mdx +0 -0
- /package/docs/{v7/examples → examples}/assert.mdx +0 -0
- /package/docs/{v7/examples → examples}/captcha-api.mdx +0 -0
- /package/docs/{v7/examples → examples}/chrome-extension.mdx +0 -0
- /package/docs/{v7/examples → examples}/drag-and-drop.mdx +0 -0
- /package/docs/{v7/examples → examples}/element-not-found.mdx +0 -0
- /package/docs/{v7/examples → examples}/findall-coffee-icons.mdx +0 -0
- /package/docs/{v7/examples → examples}/formatted-logging.mdx +0 -0
- /package/docs/{v7/examples → examples}/hover-image.mdx +0 -0
- /package/docs/{v7/examples → examples}/hover-text-with-description.mdx +0 -0
- /package/docs/{v7/examples → examples}/hover-text.mdx +0 -0
- /package/docs/{v7/examples → examples}/installer.mdx +0 -0
- /package/docs/{v7/examples → examples}/launch-vscode-linux.mdx +0 -0
- /package/docs/{v7/examples → examples}/match-image.mdx +0 -0
- /package/docs/{v7/examples → examples}/parse.mdx +0 -0
- /package/docs/{v7/examples → examples}/press-keys.mdx +0 -0
- /package/docs/{v7/examples → examples}/scroll-keyboard.mdx +0 -0
- /package/docs/{v7/examples → examples}/scroll-until-text.mdx +0 -0
- /package/docs/{v7/examples → examples}/scroll.mdx +0 -0
- /package/docs/{v7/examples → examples}/type.mdx +0 -0
- /package/docs/{v7/mcp.mdx → mcp.mdx} +0 -0
|
@@ -6,7 +6,7 @@ icon: "hand-pointer"
|
|
|
6
6
|
|
|
7
7
|
## Overview
|
|
8
8
|
|
|
9
|
-
The `doubleClick()` method
|
|
9
|
+
The `doubleClick()` method does a double-click action on an element. You can call it on an [`Element`](/core-concepts/elements) instance. Or you can use it with a selector.
|
|
10
10
|
|
|
11
11
|
## Syntax
|
|
12
12
|
|
|
@@ -30,7 +30,7 @@ When called directly on the AI client:
|
|
|
30
30
|
|
|
31
31
|
## Returns
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
It returns a `Promise<void>`. The promise resolves when the double-click action completes.
|
|
34
34
|
|
|
35
35
|
## Examples
|
|
36
36
|
|
|
@@ -95,8 +95,8 @@ expect(selectedText).toBe('TestDriver');
|
|
|
95
95
|
|
|
96
96
|
## Related Methods
|
|
97
97
|
|
|
98
|
-
- [`click()`](/
|
|
99
|
-
- [`rightClick()`](/
|
|
100
|
-
- [`mouseDown()`](/
|
|
101
|
-
- [`mouseUp()`](/
|
|
102
|
-
- [`hover()`](/
|
|
98
|
+
- [`click()`](/click) - Single click on an element
|
|
99
|
+
- [`rightClick()`](/right-click) - Right-click to open context menu
|
|
100
|
+
- [`mouseDown()`](/mouse-down) - Press mouse button without releasing
|
|
101
|
+
- [`mouseUp()`](/mouse-up) - Release mouse button
|
|
102
|
+
- [`hover()`](/hover) - Move mouse over element without clicking
|
|
@@ -1,28 +1,28 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "
|
|
3
|
-
sidebarTitle: "Elements"
|
|
2
|
+
title: "Locating Elements"
|
|
3
|
+
sidebarTitle: "Locating Elements"
|
|
4
4
|
description: "Locate and interact with UI elements using AI"
|
|
5
5
|
icon: "mouse-pointer"
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
## Overview
|
|
9
9
|
|
|
10
|
-
TestDriver
|
|
10
|
+
The TestDriver element finding system uses AI. It finds elements on the screen with natural language descriptions. The `find()` method returns an `Element` object. You can interact with the object.
|
|
11
11
|
|
|
12
12
|
## Finding Elements
|
|
13
13
|
|
|
14
14
|
### find()
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
Find an element on the screen with a natural language description.
|
|
17
17
|
|
|
18
18
|
```javascript
|
|
19
19
|
const element = await testdriver.find(description)
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
**Parameters:**
|
|
23
|
-
- `description` (string) -
|
|
23
|
+
- `description` (string) - A natural language description of the element to find
|
|
24
24
|
|
|
25
|
-
**Returns:** `Promise<Element>` - Element instance that
|
|
25
|
+
**Returns:** `Promise<Element>` - The Element instance that TestDriver found
|
|
26
26
|
|
|
27
27
|
**Example:**
|
|
28
28
|
```javascript
|
|
@@ -37,7 +37,7 @@ const redButton = await testdriver.find('red button in the top right corner');
|
|
|
37
37
|
```
|
|
38
38
|
|
|
39
39
|
<Tip>
|
|
40
|
-
Be specific in your descriptions. Include visual details, location context, or nearby text to
|
|
40
|
+
Be specific in your descriptions. Include visual details, location context, or nearby text to make the accuracy better.
|
|
41
41
|
</Tip>
|
|
42
42
|
|
|
43
43
|
## Element Class
|
|
@@ -3,7 +3,7 @@ title: "Enterprise"
|
|
|
3
3
|
sidebarTitle: "Enterprise"
|
|
4
4
|
description: "Self-hosted enterprise deployments with assisted setup and dedicated support"
|
|
5
5
|
icon: "building"
|
|
6
|
-
redirect: "/
|
|
6
|
+
redirect: "/self-hosted"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
This page has moved to [Self-Hosted](/
|
|
9
|
+
This page has moved to [Self-Hosted](/self-hosted).
|
|
@@ -8,7 +8,7 @@ mode: "wide"
|
|
|
8
8
|
|
|
9
9
|
## Overview
|
|
10
10
|
|
|
11
|
-
TestDriver
|
|
11
|
+
TestDriver gives custom error classes with full debug information. The SDK exports them. You can use them for `instanceof` checks in your tests.
|
|
12
12
|
|
|
13
13
|
```javascript
|
|
14
14
|
import TestDriver, { ElementNotFoundError, AIError } from 'testdriverai';
|
|
@@ -16,7 +16,7 @@ import TestDriver, { ElementNotFoundError, AIError } from 'testdriverai';
|
|
|
16
16
|
|
|
17
17
|
## ElementNotFoundError
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
TestDriver throws this when `find()` cannot find an element on the screen. It also throws this when you call `click()` or `hover()` on an element that TestDriver did not find.
|
|
20
20
|
|
|
21
21
|
```javascript
|
|
22
22
|
try {
|
|
@@ -37,7 +37,7 @@ try {
|
|
|
37
37
|
</ParamField>
|
|
38
38
|
|
|
39
39
|
<ParamField path="message" type="string">
|
|
40
|
-
|
|
40
|
+
A message with a debug block. The block has the element description, the cache status, the similarity scores, and the AI response details.
|
|
41
41
|
</ParamField>
|
|
42
42
|
|
|
43
43
|
<ParamField path="description" type="string">
|
|
@@ -8,9 +8,9 @@ mode: "wide"
|
|
|
8
8
|
|
|
9
9
|
## Overview
|
|
10
10
|
|
|
11
|
-
TestDriver uses [EventEmitter2](https://github.com/EventEmitter2/EventEmitter2) for its event system. Events use a
|
|
11
|
+
TestDriver uses [EventEmitter2](https://github.com/EventEmitter2/EventEmitter2) for its event system. Events use a namespace pattern with colons. They permit wildcard listeners.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Use the emitter through `testdriver.emitter`:
|
|
14
14
|
|
|
15
15
|
```javascript
|
|
16
16
|
testdriver.emitter.on('command:start', (data) => {
|
|
@@ -34,7 +34,7 @@ new EventEmitter2({
|
|
|
34
34
|
|
|
35
35
|
### Wildcard Listeners
|
|
36
36
|
|
|
37
|
-
Use `*` to match
|
|
37
|
+
Use `*` to match one level. Use `**` to match many levels:
|
|
38
38
|
|
|
39
39
|
```javascript
|
|
40
40
|
// Match all log events
|
|
@@ -157,7 +157,7 @@ testdriver.emitter.on('sandbox:progress', ({ step, message }) => {
|
|
|
157
157
|
|
|
158
158
|
### Redraw Events
|
|
159
159
|
|
|
160
|
-
Emitted during screen stability detection. See [Redraw](/
|
|
160
|
+
Emitted during screen stability detection. See [Redraw](/redraw) for more details.
|
|
161
161
|
|
|
162
162
|
| Event | Payload |
|
|
163
163
|
|---|---|
|
|
@@ -7,7 +7,7 @@ icon: "terminal"
|
|
|
7
7
|
|
|
8
8
|
## Overview
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Run shell commands (Linux) or PowerShell commands (Windows) in the sandbox.
|
|
11
11
|
|
|
12
12
|
## Syntax
|
|
13
13
|
|
|
@@ -18,28 +18,28 @@ await testdriver.exec(language, code, timeout, silent)
|
|
|
18
18
|
## Parameters
|
|
19
19
|
|
|
20
20
|
<ParamField path="language" type="string" required>
|
|
21
|
-
|
|
21
|
+
The language to run: `'sh'` (Shell/Linux) or `'pwsh'` (PowerShell/Windows)
|
|
22
22
|
</ParamField>
|
|
23
23
|
|
|
24
24
|
<ParamField path="code" type="string" required>
|
|
25
|
-
|
|
25
|
+
The code or the command to run
|
|
26
26
|
</ParamField>
|
|
27
27
|
|
|
28
28
|
<ParamField path="timeout" type="number" required>
|
|
29
|
-
|
|
29
|
+
The timeout in milliseconds
|
|
30
30
|
</ParamField>
|
|
31
31
|
|
|
32
32
|
<ParamField path="silent" type="boolean" default="false">
|
|
33
|
-
|
|
33
|
+
If `true`, TestDriver does not show the output
|
|
34
34
|
</ParamField>
|
|
35
35
|
|
|
36
36
|
## Returns
|
|
37
37
|
|
|
38
|
-
`Promise<string>` -
|
|
38
|
+
`Promise<string>` - The command output
|
|
39
39
|
|
|
40
40
|
## Shell Execution (Linux)
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
Run shell commands in the Linux sandbox.
|
|
43
43
|
|
|
44
44
|
### Basic Commands
|
|
45
45
|
|
|
@@ -313,6 +313,6 @@ describe('Code Execution', () => {
|
|
|
313
313
|
|
|
314
314
|
## Related Methods
|
|
315
315
|
|
|
316
|
-
- [`focusApplication()`](/
|
|
317
|
-
- [`find()`](/
|
|
318
|
-
- [`type()`](/
|
|
316
|
+
- [`focusApplication()`](/focus-application) - Focus apps before exec
|
|
317
|
+
- [`find()`](/find) - Locate elements visually
|
|
318
|
+
- [`type()`](/type) - Type text into inputs
|
|
@@ -7,9 +7,9 @@ icon: "wand-magic-sparkles"
|
|
|
7
7
|
|
|
8
8
|
## Overview
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Get information from the screen with AI. TestDriver returns it as a string. Describe what you want in natural language. The AI reads the screen and returns the correct value: text, numbers, labels, status messages, or other content on the screen.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
[`assert()`](/assert) returns a boolean result. But `extract()` returns the real value. Thus you can store it, compare it, or use it in later steps and in framework assertions.
|
|
13
13
|
|
|
14
14
|
## Syntax
|
|
15
15
|
|
|
@@ -21,16 +21,16 @@ const value = await testdriver.extract({ description })
|
|
|
21
21
|
## Parameters
|
|
22
22
|
|
|
23
23
|
<ParamField path="description" type="string" required>
|
|
24
|
-
|
|
24
|
+
A natural language description of the information to read from the screen.
|
|
25
25
|
</ParamField>
|
|
26
26
|
|
|
27
27
|
<Info>
|
|
28
|
-
`extract()` also accepts an options object
|
|
28
|
+
`extract()` also accepts an options object, `extract({ description })`. This is the same as the positional form. The string form is the most common.
|
|
29
29
|
</Info>
|
|
30
30
|
|
|
31
31
|
## Returns
|
|
32
32
|
|
|
33
|
-
`Promise<string>` — The information
|
|
33
|
+
`Promise<string>` — The information from the screen. TestDriver returns the value as text. Parse it or cast it yourself if you need a number or another type.
|
|
34
34
|
|
|
35
35
|
## Examples
|
|
36
36
|
|
|
@@ -101,7 +101,7 @@ expect(Number(totalText)).toBeGreaterThan(0);
|
|
|
101
101
|
<Check>
|
|
102
102
|
**Extract for detailed assertions**
|
|
103
103
|
|
|
104
|
-
Use `extract()` when a boolean [`assert()`](/
|
|
104
|
+
Use `extract()` when a boolean [`assert()`](/assert) isn't enough and you need the actual value to inspect:
|
|
105
105
|
|
|
106
106
|
```javascript
|
|
107
107
|
const confirmation = await testdriver.extract('the confirmation number');
|
|
@@ -215,11 +215,11 @@ describe('Extraction', () => {
|
|
|
215
215
|
4. The extracted value is returned as a string
|
|
216
216
|
|
|
217
217
|
<Note>
|
|
218
|
-
Like [assertions](/
|
|
218
|
+
Like [assertions](/making-assertions), `extract()` reads the screen fresh on every call — it is not cached — so it always reflects the current state of the app.
|
|
219
219
|
</Note>
|
|
220
220
|
|
|
221
221
|
## Related Methods
|
|
222
222
|
|
|
223
|
-
- [`assert()`](/
|
|
224
|
-
- [`find()`](/
|
|
225
|
-
- [`parse()`](/
|
|
223
|
+
- [`assert()`](/assert) - Verify screen state with a boolean AI judgment
|
|
224
|
+
- [`find()`](/find) - Locate elements to interact with
|
|
225
|
+
- [`parse()`](/parse) - Detect all UI elements on screen
|
|
@@ -7,7 +7,7 @@ icon: "magnifying-glass"
|
|
|
7
7
|
|
|
8
8
|
## Overview
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Find UI elements on the screen with natural language descriptions and AI. This returns an `Element` object. You can interact with the object.
|
|
11
11
|
|
|
12
12
|
## Syntax
|
|
13
13
|
|
|
@@ -27,19 +27,19 @@ const element = await testdriver.find(description, options)
|
|
|
27
27
|
|
|
28
28
|
<Expandable title="properties">
|
|
29
29
|
<ParamField path="cacheKey" type="string">
|
|
30
|
-
|
|
30
|
+
A custom cache key to store the element location. Use this to keep the cache clean when you use dynamic variables in prompts. You can also use it to share the cache between tests.
|
|
31
31
|
</ParamField>
|
|
32
32
|
|
|
33
33
|
<ParamField path="cacheThreshold" type="number" default={0.05}>
|
|
34
|
-
|
|
34
|
+
The similarity threshold (0-1) for a cache match. A lower value needs more similarity. Set it to -1 to disable the cache.
|
|
35
35
|
</ParamField>
|
|
36
36
|
|
|
37
37
|
<ParamField path="timeout" type="number" default={10000}>
|
|
38
|
-
|
|
38
|
+
The maximum time in milliseconds to poll for the element. TestDriver tries again each 5 seconds until it finds the element or the timeout ends. The default is `10000` (10 seconds). Set it to `0` to disable the poll and try one time.
|
|
39
39
|
</ParamField>
|
|
40
40
|
|
|
41
41
|
<ParamField path="confidence" type="number">
|
|
42
|
-
|
|
42
|
+
The minimum confidence threshold (0-1). If the confidence score of the found element is less than this value, the find is a failure (`element.found()` returns `false`). Use this to make sure of good matches in critical test steps.
|
|
43
43
|
</ParamField>
|
|
44
44
|
|
|
45
45
|
<ParamField path="type" type="string">
|
|
@@ -51,11 +51,11 @@ const element = await testdriver.find(description, options)
|
|
|
51
51
|
</ParamField>
|
|
52
52
|
|
|
53
53
|
<ParamField path="zoom" type="boolean" default={false}>
|
|
54
|
-
|
|
54
|
+
A two-phase zoom mode for more precision in full UIs that have many similar elements. It is disabled by default.
|
|
55
55
|
</ParamField>
|
|
56
56
|
|
|
57
57
|
<ParamField path="verify" type="boolean" default={false}>
|
|
58
|
-
|
|
58
|
+
This enables AI verification of the found element. When `true`, a second AI call makes sure that the coordinates agree with the correct element. This catches incorrect positions. It is disabled by default for less latency. When you do not set it for each call, it uses the global `verify` option from the [SDK options](/options#ai-and-element-location).
|
|
59
59
|
</ParamField>
|
|
60
60
|
|
|
61
61
|
<ParamField path="ai" type="object">
|
|
@@ -86,7 +86,7 @@ const element = await testdriver.find(description, options)
|
|
|
86
86
|
|
|
87
87
|
## Returns
|
|
88
88
|
|
|
89
|
-
`Promise<Element>` - Element instance that
|
|
89
|
+
`Promise<Element>` - The Element instance that TestDriver found automatically.
|
|
90
90
|
|
|
91
91
|
## Examples
|
|
92
92
|
|
|
@@ -142,16 +142,16 @@ console.log('Price text:', price.text);
|
|
|
142
142
|
|
|
143
143
|
## Element Object
|
|
144
144
|
|
|
145
|
-
The
|
|
145
|
+
The `Element` object that TestDriver returns gives these:
|
|
146
146
|
|
|
147
147
|
### Methods
|
|
148
148
|
|
|
149
|
-
- `found()` -
|
|
149
|
+
- `found()` - Make a check if TestDriver found the element
|
|
150
150
|
- `click(action)` - Click the element
|
|
151
|
-
- `hover()` -
|
|
151
|
+
- `hover()` - Put the cursor on the element
|
|
152
152
|
- `doubleClick()` - Double-click the element
|
|
153
153
|
- `rightClick()` - Right-click the element
|
|
154
|
-
- `find(newDescription)` -
|
|
154
|
+
- `find(newDescription)` - Find the element again with an optional new description
|
|
155
155
|
|
|
156
156
|
### Properties
|
|
157
157
|
|
|
@@ -164,11 +164,11 @@ The returned `Element` object provides:
|
|
|
164
164
|
- `width`, `height` - Element dimensions
|
|
165
165
|
- `boundingBox` - Complete bounding box
|
|
166
166
|
|
|
167
|
-
See [Elements Reference](/
|
|
167
|
+
See [Elements Reference](/elements) for complete details.
|
|
168
168
|
|
|
169
169
|
### JSON Serialization
|
|
170
170
|
|
|
171
|
-
|
|
171
|
+
You can serialize elements safely with `JSON.stringify()` for logs and for debug. TestDriver removes circular references automatically:
|
|
172
172
|
|
|
173
173
|
```javascript
|
|
174
174
|
const element = await testdriver.find('login button');
|
|
@@ -198,18 +198,18 @@ console.log(JSON.stringify(element, null, 2));
|
|
|
198
198
|
// }
|
|
199
199
|
```
|
|
200
200
|
|
|
201
|
-
|
|
202
|
-
-
|
|
203
|
-
-
|
|
204
|
-
-
|
|
205
|
-
-
|
|
201
|
+
Use this for these:
|
|
202
|
+
- To debug problems with element detection
|
|
203
|
+
- To log the details of the test
|
|
204
|
+
- To share element data between processes
|
|
205
|
+
- To examine the cache performance
|
|
206
206
|
|
|
207
207
|
## Best Practices
|
|
208
208
|
|
|
209
209
|
<Check>
|
|
210
210
|
**Be specific in descriptions**
|
|
211
211
|
|
|
212
|
-
More specific descriptions
|
|
212
|
+
More specific descriptions make the accuracy better:
|
|
213
213
|
|
|
214
214
|
```javascript
|
|
215
215
|
// ✅ Good
|
|
@@ -223,7 +223,7 @@ This is useful for:
|
|
|
223
223
|
<Check>
|
|
224
224
|
**Always check if found**
|
|
225
225
|
|
|
226
|
-
|
|
226
|
+
Make sure that TestDriver found the elements before you interact with them:
|
|
227
227
|
|
|
228
228
|
```javascript
|
|
229
229
|
const element = await testdriver.find('login button');
|
|
@@ -251,7 +251,7 @@ This is useful for:
|
|
|
251
251
|
|
|
252
252
|
## Confidence Threshold
|
|
253
253
|
|
|
254
|
-
|
|
254
|
+
Set a minimum confidence score for element matches. If the confidence is less than the threshold, `find()` makes the result "not found":
|
|
255
255
|
|
|
256
256
|
```javascript
|
|
257
257
|
// Require at least 90% confidence
|
|
@@ -265,10 +265,10 @@ if (!element.found()) {
|
|
|
265
265
|
await element.click();
|
|
266
266
|
```
|
|
267
267
|
|
|
268
|
-
|
|
269
|
-
- Critical test steps
|
|
270
|
-
-
|
|
271
|
-
-
|
|
268
|
+
Use this for these:
|
|
269
|
+
- Critical test steps. An incorrect click can cause more failures.
|
|
270
|
+
- To tell the difference between similar elements (for example, many buttons)
|
|
271
|
+
- To fail quickly when the UI changed
|
|
272
272
|
|
|
273
273
|
```javascript
|
|
274
274
|
// Combine with timeout for robust polling with confidence gate
|
|
@@ -279,11 +279,11 @@ const element = await testdriver.find('success notification', {
|
|
|
279
279
|
```
|
|
280
280
|
|
|
281
281
|
<Tip>
|
|
282
|
-
The `confidence` value is a float between 0 and 1 (
|
|
282
|
+
The `confidence` value is a float between 0 and 1 (for example, `0.9` = 90%). The AI returns its confidence with each find result. You can also read this from `element.confidence` after a good find.
|
|
283
283
|
</Tip>
|
|
284
284
|
## Element Type
|
|
285
285
|
|
|
286
|
-
Use the `type` option to
|
|
286
|
+
Use the `type` option to show which kind of element you look for. This puts your description into a more specific prompt for the AI. It makes the match accuracy better, primarily when a description is short or not clear.
|
|
287
287
|
|
|
288
288
|
```javascript
|
|
289
289
|
// Find text on the page
|
|
@@ -310,11 +310,11 @@ const el = await testdriver.find('the blue submit button', { type: 'any' });
|
|
|
310
310
|
| `"any"` | Original description (no wrapping) |
|
|
311
311
|
|
|
312
312
|
<Tip>
|
|
313
|
-
|
|
313
|
+
Use this primarily for short descriptions such as `"Submit"` or `"Login"`. In these, the AI can be not sure to look for a button, a link, or visible text. When you give the `type`, the description becomes clear.
|
|
314
314
|
</Tip>
|
|
315
315
|
## Polling for Dynamic Elements
|
|
316
316
|
|
|
317
|
-
By default, `find()` polls for
|
|
317
|
+
By default, `find()` polls for a maximum of 10 seconds (it tries again each 5 seconds) until it finds the element. You can change this with the `timeout` option:
|
|
318
318
|
|
|
319
319
|
```javascript
|
|
320
320
|
// Uses default 10s timeout - polls every 5 seconds
|
|
@@ -330,18 +330,18 @@ const element = await testdriver.find('login button', { timeout: 0 });
|
|
|
330
330
|
```
|
|
331
331
|
|
|
332
332
|
The `timeout` option:
|
|
333
|
-
-
|
|
334
|
-
-
|
|
335
|
-
- Stops when the element
|
|
336
|
-
- Logs progress during
|
|
337
|
-
- Returns the element (check `element.found()` if not
|
|
338
|
-
- Set to `0` to disable
|
|
333
|
+
- Has a default of `10000` (10 seconds)
|
|
334
|
+
- Tries to find the element again each 5 seconds
|
|
335
|
+
- Stops when it finds the element or the timeout ends
|
|
336
|
+
- Logs the progress during the poll
|
|
337
|
+
- Returns the element (make a check with `element.found()` if it does not throw an error on a failure)
|
|
338
|
+
- Set it to `0` to disable the poll and try one time
|
|
339
339
|
|
|
340
340
|
## Zoom Mode
|
|
341
341
|
|
|
342
|
-
Zoom mode is **disabled by default**. It uses a two-phase
|
|
342
|
+
Zoom mode is **disabled by default**. It uses a two-phase method for more precision when it finds elements, primarily in full UIs that have many similar elements.
|
|
343
343
|
|
|
344
|
-
To enable zoom for a specific find call,
|
|
344
|
+
To enable zoom for a specific find call, give `zoom: true`:
|
|
345
345
|
|
|
346
346
|
```javascript
|
|
347
347
|
// Enable zoom for better precision in crowded UIs
|
|
@@ -354,22 +354,22 @@ const largeButton = await testdriver.find('big hero button');
|
|
|
354
354
|
|
|
355
355
|
### How Zoom Mode Works
|
|
356
356
|
|
|
357
|
-
1. **Phase 1**: AI
|
|
358
|
-
2. **Phase 2**:
|
|
359
|
-
3. **Phase 3**: AI
|
|
360
|
-
4. **Result**:
|
|
357
|
+
1. **Phase 1**: The AI finds the approximate location of the element.
|
|
358
|
+
2. **Phase 2**: TestDriver makes a 30% crop of the screen around that location.
|
|
359
|
+
3. **Phase 3**: The AI does the precise location on the cropped image.
|
|
360
|
+
4. **Result**: TestDriver changes the coordinates back to the absolute screen position.
|
|
361
361
|
|
|
362
|
-
This two-phase
|
|
362
|
+
This two-phase method gives the AI a higher-resolution view of the target area. It makes the accuracy better when many similar elements are near together.
|
|
363
363
|
|
|
364
364
|
<Tip>
|
|
365
|
-
|
|
366
|
-
-
|
|
367
|
-
- You need
|
|
365
|
+
Enable zoom with `zoom: true` when:
|
|
366
|
+
- You target small elements in full UIs that have many similar elements
|
|
367
|
+
- You need more precision for UI elements that are near together
|
|
368
368
|
</Tip>
|
|
369
369
|
|
|
370
370
|
## Verify Mode
|
|
371
371
|
|
|
372
|
-
Verify mode is **disabled by default**. When enabled, a second AI call
|
|
372
|
+
Verify mode is **disabled by default**. When it is enabled, a second AI call makes sure that the coordinates from `find()` agree with the correct element. This catches incorrect positions.
|
|
373
373
|
|
|
374
374
|
```javascript
|
|
375
375
|
// Enable verification for critical interactions
|
|
@@ -379,13 +379,13 @@ await deleteBtn.click();
|
|
|
379
379
|
|
|
380
380
|
### How Verify Mode Works
|
|
381
381
|
|
|
382
|
-
1. **Phase 1**: AI
|
|
383
|
-
2. **Phase 2**: A second AI call
|
|
384
|
-
3. **Result**: If verification fails, the find
|
|
382
|
+
1. **Phase 1**: The AI finds the element and returns coordinates.
|
|
383
|
+
2. **Phase 2**: A second AI call looks at the screenshot at those coordinates. It makes sure that the element agrees with the description.
|
|
384
|
+
3. **Result**: If the verification fails, TestDriver tries the find again or marks it "not found".
|
|
385
385
|
|
|
386
386
|
### Combining Zoom and Verify
|
|
387
387
|
|
|
388
|
-
For maximum accuracy, enable
|
|
388
|
+
For the maximum accuracy, enable `zoom` and `verify` together. Use this for critical interactions. A click on the wrong element can cause more failures:
|
|
389
389
|
|
|
390
390
|
```javascript
|
|
391
391
|
// Maximum accuracy: zoom for precision + verify to catch hallucinations
|
|
@@ -398,13 +398,13 @@ await element.click();
|
|
|
398
398
|
|
|
399
399
|
## Cache Options
|
|
400
400
|
|
|
401
|
-
When a test completes
|
|
401
|
+
When a test completes correctly, TestDriver caches the result of each `find()`. On later runs, TestDriver uses the cached match again. It does not make a new AI call. This finds the same element much more quickly. The cache is in your [dashboard](https://console.testdriver.ai/cache). TestDriver shares it between runs. Read the [Cache](/cache) page to see how the match, the thresholds, and the invalidation work.
|
|
402
402
|
|
|
403
|
-
Control
|
|
403
|
+
Control the cache to make the performance better, primarily when you use dynamic variables in prompts.
|
|
404
404
|
|
|
405
405
|
### Custom Cache Key
|
|
406
406
|
|
|
407
|
-
Use `cacheKey` to
|
|
407
|
+
Use `cacheKey` to keep the cache clean when prompts have variables:
|
|
408
408
|
|
|
409
409
|
```javascript
|
|
410
410
|
// ❌ Without cacheKey - creates new cache entry for each email value
|
|
@@ -426,7 +426,7 @@ await testdriver.find(`order ${orderId} status`, {
|
|
|
426
426
|
|
|
427
427
|
### Cache Threshold
|
|
428
428
|
|
|
429
|
-
Control how similar a cached result must be
|
|
429
|
+
Control how similar a cached result must be before TestDriver uses it again:
|
|
430
430
|
|
|
431
431
|
```javascript
|
|
432
432
|
// Default: 95% similarity required
|
|
@@ -450,12 +450,12 @@ await testdriver.find('submit button', {
|
|
|
450
450
|
```
|
|
451
451
|
|
|
452
452
|
<Tip>
|
|
453
|
-
By default, TestDriver
|
|
453
|
+
By default, TestDriver makes a cache key automatically from the SHA-256 hash of your test file. When you change your test file, the hash changes automatically. This makes the old cache entries not valid.
|
|
454
454
|
</Tip>
|
|
455
455
|
|
|
456
456
|
### Manual Polling (Alternative)
|
|
457
457
|
|
|
458
|
-
If you need custom
|
|
458
|
+
If you need custom poll logic:
|
|
459
459
|
|
|
460
460
|
```javascript
|
|
461
461
|
async function waitForElement(testdriver, description, timeout = 30000) {
|
|
@@ -595,10 +595,10 @@ describe('Element Finding', () => {
|
|
|
595
595
|
|
|
596
596
|
## Related Methods
|
|
597
597
|
|
|
598
|
-
- [`click()`](/
|
|
599
|
-
- [`hover()`](/
|
|
600
|
-
- [`assert()`](/
|
|
601
|
-
- [Elements Reference](/
|
|
598
|
+
- [`click()`](/click) - Click on found elements
|
|
599
|
+
- [`hover()`](/hover) - Hover over elements
|
|
600
|
+
- [`assert()`](/assert) - Verify element states
|
|
601
|
+
- [Elements Reference](/elements) - Complete Element API
|
|
602
602
|
|
|
603
603
|
---
|
|
604
604
|
|
|
@@ -7,7 +7,7 @@ icon: "window-maximize"
|
|
|
7
7
|
|
|
8
8
|
## Overview
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Move a specific application window to the front. Make it the active window for interactions.
|
|
11
11
|
|
|
12
12
|
## Syntax
|
|
13
13
|
|
|
@@ -18,12 +18,12 @@ await testdriver.focusApplication(name)
|
|
|
18
18
|
## Parameters
|
|
19
19
|
|
|
20
20
|
<ParamField path="name" type="string" required>
|
|
21
|
-
|
|
21
|
+
The application name (for example, `'Google Chrome'`, `'Microsoft Edge'`, `'Notepad'`)
|
|
22
22
|
</ParamField>
|
|
23
23
|
|
|
24
24
|
## Returns
|
|
25
25
|
|
|
26
|
-
`Promise<string>` -
|
|
26
|
+
`Promise<string>` - The result message
|
|
27
27
|
|
|
28
28
|
## Examples
|
|
29
29
|
|
|
@@ -289,6 +289,6 @@ describe('Multi-Application Workflow', () => {
|
|
|
289
289
|
|
|
290
290
|
## Related Methods
|
|
291
291
|
|
|
292
|
-
- [`exec()`](/
|
|
293
|
-
- [`pressKeys()`](/
|
|
294
|
-
- [`find()`](/
|
|
292
|
+
- [`exec()`](/exec) - Launch applications with PowerShell
|
|
293
|
+
- [`pressKeys()`](/press-keys) - Use Alt+Tab to switch windows
|
|
294
|
+
- [`find()`](/find) - Locate elements in the focused window
|