15. Test a custom tool on a real device

Run test performs a real operation on the connected device. It runs the current editor buffer, including unsaved changes. It is not the simulated administrator Preview and does not require the tool to be published.

Use a test device and a script whose effects you understand. The test author's explicit Run test action authorizes that run; the Harness chat's normal plan-review interaction is not the testing UI. Native connection, platform, Remote Control, and administrator requirements still apply.

Connect the right device

1. Expand Device testing at the bottom of the custom-tool editor.
2. Choose one of Your open support sessions, then select its Attach action. You need normal access to that session, and its device must match the draft's platform.
3. Alternatively, use Create new session, give the device's user the PIN/link, and wait for the device to connect. Request administrator access on connect only if your test needs it.
4. Wait for Ready and Remote Control granted. Confirm the session/device before dispatching.
5. Use Open viewer when you need to inspect the remote screen or complete a normal permission workflow.

The session picker can attach to a session that is also open in the viewer.

Windows scripts need a compatible Windows device; macOS Bash scripts need a compatible Mac. An Administrator script needs actual administrator execution access, not merely an admin-looking user account. A permission denial, platform mismatch, or disconnected device should block testing until resolved.

The editor's testing connection and a normal viewer connection can coexist. They may affect which connection currently has Remote Control. In this walkthrough, the viewer temporarily fell back to Ask while testing held control. After testing, detach and restore viewer control if needed before continuing Agent work.

Set inputs and run the current buffer

1. Inspect the script, role, timeout, and Test inputs.
2. For a parameterized tool, distinguish omitted input from explicit values. Test meaningful cases such as empty string, 0, and false when they are valid for the tool.
3. Select Run test once.
4. Watch Running… and the elapsed time. Wait for the operation's actual result before trying again.

No save or publication is required. The draft in this example only reads the current PowerShell runtime version.

Inspect the result

The result panel shows execution state, duration, and exit code. Use Standard output and Standard error to inspect both streams; Copy exports the selected stream.

The captured run completed in 1.9 seconds, with exit code 0, and returned:

{"powershell_version":"5.1.26100.9711"}

That proves this exact draft ran successfully in that test's context. It does not establish that every script, parameter value, Windows version, privilege state, or future publication will work.

Use the result to improve the script

Select Send result to assistant to stage a test attachment. Choose whether to include stdout and stderr, inspect the attachment, edit the prepared question, and then select Send. The attachment includes the tested script snapshot, inputs, exit status, and any truncation indicator, so the assistant can reason about the code that actually ran.

For example, ask “Why did this parameter fail?” or “Keep the script read-only and handle this empty result.” Review proposed changes, apply them to the draft, and explicitly run another test. Sending a result does not automatically execute the assistant's suggested fix.

If you edit source, parameters, or execution properties after a run, an older result can refer to an earlier snapshot. Check that relationship before deciding the current draft is validated.

Handle timeouts and connection changes

Before publishing, test expected output, invalid/omitted inputs, no-match/error behavior, role requirements, and actual effects. Verify state-changing scripts by checking the resulting device state, not just an exit code. Keep production devices out of exploratory tests that can interrupt users.