@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.
Files changed (174) hide show
  1. package/ai/skills/testdriver-assert/SKILL.md +5 -5
  2. package/ai/skills/testdriver-caching/SKILL.md +2 -2
  3. package/ai/skills/testdriver-changelog/SKILL.md +186 -0
  4. package/ai/skills/testdriver-claude-mcp-plugin/SKILL.md +208 -0
  5. package/ai/skills/testdriver-click/SKILL.md +13 -13
  6. package/ai/skills/testdriver-client/SKILL.md +1 -1
  7. package/ai/skills/testdriver-debugging-with-screenshots/SKILL.md +5 -5
  8. package/ai/skills/testdriver-double-click/SKILL.md +7 -7
  9. package/ai/skills/testdriver-enterprise/SKILL.md +1 -1
  10. package/ai/skills/testdriver-events/SKILL.md +1 -1
  11. package/ai/skills/testdriver-exec/SKILL.md +10 -10
  12. package/ai/skills/testdriver-extract/SKILL.md +6 -6
  13. package/ai/skills/testdriver-find/SKILL.md +61 -61
  14. package/ai/skills/testdriver-focus-application/SKILL.md +6 -6
  15. package/ai/skills/testdriver-generating-tests/SKILL.md +3 -3
  16. package/ai/skills/testdriver-hosted/SKILL.md +3 -3
  17. package/ai/skills/testdriver-hover/SKILL.md +6 -6
  18. package/ai/skills/testdriver-making-assertions/SKILL.md +2 -2
  19. package/ai/skills/testdriver-mouse-down/SKILL.md +9 -9
  20. package/ai/skills/testdriver-mouse-up/SKILL.md +9 -9
  21. package/ai/skills/testdriver-parse/SKILL.md +4 -4
  22. package/ai/skills/testdriver-performing-actions/SKILL.md +4 -4
  23. package/ai/skills/testdriver-press-keys/SKILL.md +5 -5
  24. package/ai/skills/testdriver-quickstart/SKILL.md +51 -54
  25. package/ai/skills/testdriver-redraw/SKILL.md +1 -1
  26. package/ai/skills/testdriver-right-click/SKILL.md +7 -7
  27. package/ai/skills/testdriver-screenshot/SKILL.md +9 -9
  28. package/ai/skills/testdriver-scroll/SKILL.md +13 -13
  29. package/ai/skills/testdriver-self-hosted/SKILL.md +1 -1
  30. package/ai/skills/testdriver-type/SKILL.md +7 -7
  31. package/ai/skills/testdriver-wait/SKILL.md +5 -5
  32. package/ai/skills/testdriver-what-is-testdriver/SKILL.md +11 -11
  33. package/docs/{v7/_drafts → _drafts}/agents.mdx +1 -1
  34. package/docs/{v7/_drafts → _drafts}/best-practices.mdx +4 -4
  35. package/docs/{v7/_drafts → _drafts}/caching-selectors.mdx +3 -3
  36. package/docs/{v7/_drafts → _drafts}/configuration.mdx +4 -4
  37. package/docs/{v7/_drafts → _drafts}/debugging.mdx +4 -4
  38. package/docs/{v7/_drafts → _drafts}/error-handling.mdx +4 -4
  39. package/docs/{v7/_drafts → _drafts}/faq.mdx +7 -7
  40. package/docs/{v7/_drafts → _drafts}/installation.mdx +2 -2
  41. package/docs/{v7/_drafts → _drafts}/migration.mdx +4 -4
  42. package/docs/{v7/_drafts → _drafts}/observable.mdx +3 -3
  43. package/docs/{v7/_drafts → _drafts}/powerful.mdx +4 -4
  44. package/docs/{v7/_drafts → _drafts}/readme.mdx +11 -11
  45. package/docs/{v7/_drafts → _drafts}/reports.mdx +4 -4
  46. package/docs/{v7/_drafts → _drafts}/scalable.mdx +10 -10
  47. package/docs/{v7/_drafts → _drafts}/troubleshooting.mdx +4 -4
  48. package/docs/{v7/_drafts → _drafts}/vitest-plugin.mdx +2 -2
  49. package/docs/{v7/_drafts → _drafts}/vitest.mdx +9 -9
  50. package/docs/_scripts/generate-examples.js +9 -10
  51. package/docs/_scripts/generate-skills.js +4 -4
  52. package/docs/{v7/agent.mdx → agent.mdx} +17 -17
  53. package/docs/{v7/assert.mdx → assert.mdx} +5 -5
  54. package/docs/{v7/aws-setup.mdx → aws-setup.mdx} +6 -6
  55. package/docs/{v7/cache.mdx → cache.mdx} +9 -9
  56. package/docs/{v7/caching.mdx → caching.mdx} +13 -12
  57. package/docs/{v7/captcha.mdx → captcha.mdx} +7 -7
  58. package/docs/changelog.mdx +13 -13
  59. package/docs/{v7/ci-cd.mdx → ci-cd.mdx} +10 -10
  60. package/docs/{v7/click.mdx → click.mdx} +13 -13
  61. package/docs/client.mdx +323 -0
  62. package/docs/{v7/copilot → copilot}/auto-healing.mdx +2 -2
  63. package/docs/{v7/copilot → copilot}/running-tests.mdx +8 -8
  64. package/docs/{v7/customizing-devices.mdx → customizing-devices.mdx} +1 -1
  65. package/docs/{v7/dashcam.mdx → dashcam.mdx} +3 -3
  66. package/docs/{v7/debugging-with-screenshots.mdx → debugging-with-screenshots.mdx} +12 -12
  67. package/docs/docs.json +429 -288
  68. package/docs/{v7/double-click.mdx → double-click.mdx} +7 -7
  69. package/docs/{v7/elements.mdx → elements.mdx} +7 -7
  70. package/docs/{v7/enterprise.mdx → enterprise.mdx} +2 -2
  71. package/docs/{v7/errors.mdx → errors.mdx} +3 -3
  72. package/docs/{v7/events.mdx → events.mdx} +4 -4
  73. package/docs/{v7/exec.mdx → exec.mdx} +10 -10
  74. package/docs/{v7/extract.mdx → extract.mdx} +10 -10
  75. package/docs/{v7/find.mdx → find.mdx} +61 -61
  76. package/docs/{v7/focus-application.mdx → focus-application.mdx} +6 -6
  77. package/docs/{v7/generating-tests.mdx → generating-tests.mdx} +10 -10
  78. package/docs/guide/best-practices-polling.mdx +6 -1
  79. package/docs/{v7/hosted.mdx → hosted.mdx} +7 -7
  80. package/docs/{v7/hover.mdx → hover.mdx} +6 -6
  81. package/docs/interacting-with-your-app.mdx +198 -0
  82. package/docs/locating-elements.mdx +423 -0
  83. package/docs/{v7/making-assertions.mdx → making-assertions.mdx} +7 -7
  84. package/docs/{v7/mouse-down.mdx → mouse-down.mdx} +9 -9
  85. package/docs/{v7/mouse-up.mdx → mouse-up.mdx} +9 -9
  86. package/docs/options.mdx +320 -0
  87. package/docs/{v7/parse.mdx → parse.mdx} +12 -12
  88. package/docs/{v7/performing-actions.mdx → performing-actions.mdx} +11 -11
  89. package/docs/{v7/press-keys.mdx → press-keys.mdx} +5 -5
  90. package/docs/{v7/provision.mdx → provision.mdx} +9 -9
  91. package/docs/quickstart-cli.mdx +437 -0
  92. package/docs/quickstart-github.mdx +54 -0
  93. package/docs/quickstart-manual.mdx +135 -0
  94. package/docs/quickstart.mdx +22 -0
  95. package/docs/{v7/redraw.mdx → redraw.mdx} +7 -7
  96. package/docs/{v7/reusable-code.mdx → reusable-code.mdx} +3 -3
  97. package/docs/{v7/right-click.mdx → right-click.mdx} +7 -7
  98. package/docs/{v7/screenshot.mdx → screenshot.mdx} +9 -9
  99. package/docs/{v7/screenshots.mdx → screenshots.mdx} +3 -3
  100. package/docs/{v7/scroll.mdx → scroll.mdx} +13 -13
  101. package/docs/{v7/secrets.mdx → secrets.mdx} +4 -4
  102. package/docs/{v7/self-hosted.mdx → self-hosted.mdx} +7 -7
  103. package/docs/{v7/test-results-json.mdx → test-results-json.mdx} +4 -4
  104. package/docs/{v7/type.mdx → type.mdx} +7 -7
  105. package/docs/{v7/variables.mdx → variables.mdx} +2 -2
  106. package/docs/{v7/wait.mdx → wait.mdx} +5 -5
  107. package/docs/what-is-testdriver.mdx +54 -0
  108. package/lib/environments.json +1 -1
  109. package/lib/github-comment.mjs +2 -3
  110. package/package.json +1 -1
  111. package/scripts/generate-skills.js +1 -1
  112. package/docs/v7/client.mdx +0 -486
  113. package/docs/v7/quickstart.mdx +0 -451
  114. package/docs/v7/what-is-testdriver.mdx +0 -54
  115. /package/docs/{v7/_drafts → _drafts}/architecture.mdx +0 -0
  116. /package/docs/{v7/_drafts → _drafts}/auto-cache-key.mdx +0 -0
  117. /package/docs/{v7/_drafts → _drafts}/awesome-logs-quick-ref.mdx +0 -0
  118. /package/docs/{v7/_drafts → _drafts}/cli-to-sdk-migration.mdx +0 -0
  119. /package/docs/{v7/_drafts → _drafts}/commands/assert.mdx +0 -0
  120. /package/docs/{v7/_drafts → _drafts}/commands/exec.mdx +0 -0
  121. /package/docs/{v7/_drafts → _drafts}/commands/focus-application.mdx +0 -0
  122. /package/docs/{v7/_drafts → _drafts}/commands/hover-image.mdx +0 -0
  123. /package/docs/{v7/_drafts → _drafts}/commands/hover-text.mdx +0 -0
  124. /package/docs/{v7/_drafts → _drafts}/commands/if.mdx +0 -0
  125. /package/docs/{v7/_drafts → _drafts}/commands/match-image.mdx +0 -0
  126. /package/docs/{v7/_drafts → _drafts}/commands/press-keys.mdx +0 -0
  127. /package/docs/{v7/_drafts → _drafts}/commands/remember.mdx +0 -0
  128. /package/docs/{v7/_drafts → _drafts}/commands/run.mdx +0 -0
  129. /package/docs/{v7/_drafts → _drafts}/commands/scroll-until-image.mdx +0 -0
  130. /package/docs/{v7/_drafts → _drafts}/commands/scroll-until-text.mdx +0 -0
  131. /package/docs/{v7/_drafts → _drafts}/commands/scroll.mdx +0 -0
  132. /package/docs/{v7/_drafts → _drafts}/commands/type.mdx +0 -0
  133. /package/docs/{v7/_drafts → _drafts}/commands/wait-for-image.mdx +0 -0
  134. /package/docs/{v7/_drafts → _drafts}/commands/wait-for-text.mdx +0 -0
  135. /package/docs/{v7/_drafts → _drafts}/commands/wait.mdx +0 -0
  136. /package/docs/{v7/_drafts → _drafts}/contributing.mdx +0 -0
  137. /package/docs/{v7/_drafts → _drafts}/dashcam-title-feature.mdx +0 -0
  138. /package/docs/{v7/_drafts → _drafts}/hooks.mdx +0 -0
  139. /package/docs/{v7/_drafts → _drafts}/init-command.mdx +0 -0
  140. /package/docs/{v7/_drafts → _drafts}/playwright.mdx +0 -0
  141. /package/docs/{v7/_drafts → _drafts}/plugin-migration.mdx +0 -0
  142. /package/docs/{v7/_drafts → _drafts}/presets.mdx +0 -0
  143. /package/docs/{v7/_drafts → _drafts}/progressive-disclosure.mdx +0 -0
  144. /package/docs/{v7/_drafts → _drafts}/provision.mdx +0 -0
  145. /package/docs/{v7/_drafts → _drafts}/quick-start-test-recording.mdx +0 -0
  146. /package/docs/{v7/_drafts → _drafts}/screenshot.mdx +0 -0
  147. /package/docs/{v7/_drafts → _drafts}/sdk-awesome-logs.mdx +0 -0
  148. /package/docs/{v7/_drafts → _drafts}/sdk-browser-rendering.mdx +0 -0
  149. /package/docs/{v7/_drafts → _drafts}/sdk-migration.mdx +0 -0
  150. /package/docs/{v7/_drafts → _drafts}/sdk-v7-complete.mdx +0 -0
  151. /package/docs/{v7/_drafts → _drafts}/self-hosting.mdx +0 -0
  152. /package/docs/{v7/_drafts → _drafts}/test-recording.mdx +0 -0
  153. /package/docs/{v7/_drafts → _drafts}/writing-tests.mdx +0 -0
  154. /package/docs/{v7/examples → examples}/ai.mdx +0 -0
  155. /package/docs/{v7/examples → examples}/assert.mdx +0 -0
  156. /package/docs/{v7/examples → examples}/captcha-api.mdx +0 -0
  157. /package/docs/{v7/examples → examples}/chrome-extension.mdx +0 -0
  158. /package/docs/{v7/examples → examples}/drag-and-drop.mdx +0 -0
  159. /package/docs/{v7/examples → examples}/element-not-found.mdx +0 -0
  160. /package/docs/{v7/examples → examples}/findall-coffee-icons.mdx +0 -0
  161. /package/docs/{v7/examples → examples}/formatted-logging.mdx +0 -0
  162. /package/docs/{v7/examples → examples}/hover-image.mdx +0 -0
  163. /package/docs/{v7/examples → examples}/hover-text-with-description.mdx +0 -0
  164. /package/docs/{v7/examples → examples}/hover-text.mdx +0 -0
  165. /package/docs/{v7/examples → examples}/installer.mdx +0 -0
  166. /package/docs/{v7/examples → examples}/launch-vscode-linux.mdx +0 -0
  167. /package/docs/{v7/examples → examples}/match-image.mdx +0 -0
  168. /package/docs/{v7/examples → examples}/parse.mdx +0 -0
  169. /package/docs/{v7/examples → examples}/press-keys.mdx +0 -0
  170. /package/docs/{v7/examples → examples}/scroll-keyboard.mdx +0 -0
  171. /package/docs/{v7/examples → examples}/scroll-until-text.mdx +0 -0
  172. /package/docs/{v7/examples → examples}/scroll.mdx +0 -0
  173. /package/docs/{v7/examples → examples}/type.mdx +0 -0
  174. /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 performs a double-click action on an element. You can either call it on an [`Element`](/v7/core-concepts/elements) instance or use it directly with a selector.
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
- Returns a `Promise<void>` that resolves when the double-click action completes.
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()`](/v7/click) - Single click on an element
99
- - [`rightClick()`](/v7/right-click) - Right-click to open context menu
100
- - [`mouseDown()`](/v7/mouse-down) - Press mouse button without releasing
101
- - [`mouseUp()`](/v7/mouse-up) - Release mouse button
102
- - [`hover()`](/v7/hover) - Move mouse over element without clicking
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: "Element Finding"
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's element finding system uses AI to locate elements on screen using natural language descriptions. The `find()` method returns an `Element` object that you can interact with.
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
- Locate an element on screen using a natural language description.
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) - Natural language description of the element to find
23
+ - `description` (string) - A natural language description of the element to find
24
24
 
25
- **Returns:** `Promise<Element>` - Element instance that has been located
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 improve accuracy.
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: "/v7/self-hosted"
6
+ redirect: "/self-hosted"
7
7
  ---
8
8
 
9
- This page has moved to [Self-Hosted](/v7/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 provides custom error classes with rich debugging information. These are exported from the SDK and can be used for `instanceof` checks in your tests.
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
- Thrown when `find()` cannot locate an element on screen, or when calling `click()`/`hover()` on an unfound element.
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
- Enhanced message with a debug block containing element description, cache status, similarity scores, and AI response details.
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 colon-delimited namespace pattern and support wildcard listeners.
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
- Access the emitter through `testdriver.emitter`:
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 a single level or `**` to match multiple levels:
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](/v7/redraw) for more details.
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
- Execute shell commands (Linux) or PowerShell commands (Windows) in the sandbox environment.
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
- Language to execute: `'sh'` (Shell/Linux) or `'pwsh'` (PowerShell/Windows)
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
- Code or command to execute
25
+ The code or the command to run
26
26
  </ParamField>
27
27
 
28
28
  <ParamField path="timeout" type="number" required>
29
- Timeout in milliseconds
29
+ The timeout in milliseconds
30
30
  </ParamField>
31
31
 
32
32
  <ParamField path="silent" type="boolean" default="false">
33
- Suppress output if `true`
33
+ If `true`, TestDriver does not show the output
34
34
  </ParamField>
35
35
 
36
36
  ## Returns
37
37
 
38
- `Promise<string>` - Command output
38
+ `Promise<string>` - The command output
39
39
 
40
40
  ## Shell Execution (Linux)
41
41
 
42
- Execute shell commands in the Linux sandbox.
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()`](/v7/focus-application) - Focus apps before exec
317
- - [`find()`](/v7/find) - Locate elements visually
318
- - [`type()`](/v7/type) - Type text into inputs
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
- Extract information from the current screen using AI and return it as a string. Describe what you want in natural language, and the AI reads the screen and returns the matching value text, numbers, labels, status messages, or any other on-screen content.
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
- Unlike [`assert()`](/v7/assert), which returns a boolean verdict, `extract()` returns the actual value so you can store it, compare it, or feed it into later steps and framework assertions.
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
- Natural language description of the information to read from the screen.
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 `extract({ description })` which is equivalent to the positional form. The bare string form is the most common.
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 read from the screen. Returns the extracted value as text; parse or cast it yourself if you need a number or other type.
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()`](/v7/assert) isn't enough and you need the actual value to inspect:
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](/v7/making-assertions), `extract()` reads the screen fresh on every call — it is not cached — so it always reflects the current state of the app.
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()`](/v7/assert) - Verify screen state with a boolean AI judgment
224
- - [`find()`](/v7/find) - Locate elements to interact with
225
- - [`parse()`](/v7/parse) - Detect all UI elements on screen
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
- Locate UI elements on screen using AI-powered natural language descriptions. Returns an `Element` object that can be interacted with.
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
- Custom cache key for storing element location. Use this to prevent cache pollution when using dynamic variables in prompts, or to share cache across tests.
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
- Similarity threshold (0-1) for cache matching. Lower values require more similarity. Set to -1 to disable cache.
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
- Maximum time in milliseconds to poll for the element. Retries every 5 seconds until found or timeout expires. Defaults to `10000` (10 seconds). Set to `0` to disable polling and make a single attempt.
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
- Minimum confidence threshold (0-1). If the AI's confidence score for the found element is below this value, the find will be treated as a failure (`element.found()` returns `false`). Useful for ensuring high-quality matches in critical test steps.
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
- Two-phase zoom mode for better precision in crowded UIs with many similar elements. Disabled by default.
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
- Enable AI verification of the located element. When `true`, a second AI call checks that the coordinates returned actually correspond to the requested element, catching hallucinated or incorrect positions. Disabled by default for lower latency. Defaults to the global `verify` option set on the [SDK constructor](/v7/client) when not specified per call.
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 has been automatically located
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 returned `Element` object provides:
145
+ The `Element` object that TestDriver returns gives these:
146
146
 
147
147
  ### Methods
148
148
 
149
- - `found()` - Check if element was located
149
+ - `found()` - Make a check if TestDriver found the element
150
150
  - `click(action)` - Click the element
151
- - `hover()` - Hover over the element
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)` - Re-locate with optional new description
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](/v7/elements) for complete details.
167
+ See [Elements Reference](/elements) for complete details.
168
168
 
169
169
  ### JSON Serialization
170
170
 
171
- Elements can be safely serialized using `JSON.stringify()` for logging and debugging. Circular references are automatically removed:
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
- This is useful for:
202
- - Debugging element detection issues
203
- - Logging test execution details
204
- - Sharing element information across processes
205
- - Analyzing cache performance
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 improve accuracy:
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
- Verify elements were located before interacting:
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
- Require a minimum AI confidence score for element matches. If the confidence is below the threshold, `find()` treats the result as not found:
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
- This is useful for:
269
- - Critical test steps where an incorrect click could cause cascading failures
270
- - Distinguishing between similar elements (e.g., multiple buttons)
271
- - Failing fast when the UI has changed unexpectedly
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 (e.g., `0.9` = 90%). The AI returns its confidence with each find result, which you can also read from `element.confidence` after a successful find.
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 hint what kind of element you're looking for. This wraps your description into a more specific prompt for the AI, improving match accuracy especially when users provide short or ambiguous descriptions.
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
- This is particularly useful for short descriptions like `"Submit"` or `"Login"` where the AI may not know whether to look for a button, a link, or visible text. Specifying `type` removes the ambiguity.
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 up to 10 seconds (retrying every 5 seconds) until the element is found. You can customize this with the `timeout` option:
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
- - Defaults to `10000` (10 seconds)
334
- - Retries finding the element every 5 seconds
335
- - Stops when the element is found or the timeout expires
336
- - Logs progress during polling
337
- - Returns the element (check `element.found()` if not throwing on failure)
338
- - Set to `0` to disable polling and make a single attempt
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 approach for better precision when locating elements, especially in crowded UIs with many similar elements.
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, pass `zoom: true`:
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 identifies the approximate location of the element
358
- 2. **Phase 2**: A 30% crop of the screen is created around that location
359
- 3. **Phase 3**: AI performs precise location on the zoomed/cropped image
360
- 4. **Result**: Coordinates are converted back to absolute screen position
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 approach gives the AI a higher-resolution view of the target area, improving accuracy when multiple similar elements are close together.
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
- You may want to enable zoom with `zoom: true` when:
366
- - Targeting small elements in crowded UIs with many similar elements
367
- - You need extra precision for closely spaced UI elements
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 checks that the coordinates returned by `find()` actually correspond to the requested element, catching hallucinated or incorrect positions.
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 locates the element and returns coordinates
383
- 2. **Phase 2**: A second AI call examines the screenshot at those coordinates to confirm the element matches the description
384
- 3. **Result**: If verification fails, the find is retried or marked as not found
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 both `zoom` and `verify` together. This is useful for critical interactions where clicking the wrong element could cause cascading failures:
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 successfully, the result of each `find()` is cached. On later runs, TestDriver reuses the cached match instead of making a fresh AI call, which significantly speeds up locating the same element. The cache lives in your [dashboard](https://console.testdriver.ai/cache) and is shared across runs see the [Cache](/v7/cache) page for how matching, thresholds, and invalidation work.
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 caching behavior to optimize performance, especially when using dynamic variables in prompts.
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 prevent cache pollution when prompts contain variables:
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 to reuse it:
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 auto-generates a cache key from the SHA-256 hash of your test file. When you modify your test file, the hash changes automatically, invalidating stale cache entries.
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 polling logic:
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()`](/v7/click) - Click on found elements
599
- - [`hover()`](/v7/hover) - Hover over elements
600
- - [`assert()`](/v7/assert) - Verify element states
601
- - [Elements Reference](/v7/elements) - Complete Element API
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
- Bring a specific application window to the foreground and make it the active window for interactions.
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
- Application name (e.g., `'Google Chrome'`, `'Microsoft Edge'`, `'Notepad'`)
21
+ The application name (for example, `'Google Chrome'`, `'Microsoft Edge'`, `'Notepad'`)
22
22
  </ParamField>
23
23
 
24
24
  ## Returns
25
25
 
26
- `Promise<string>` - Result message
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()`](/v7/exec) - Launch applications with PowerShell
293
- - [`pressKeys()`](/v7/press-keys) - Use Alt+Tab to switch windows
294
- - [`find()`](/v7/find) - Locate elements in the focused window
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