Introduction

To integrate Playwright with an Agent, the common approach is to create a semantic abstraction layer: splitting test, install, and show-report into multiple tools and designing a parameter schema for each subcommand. The problem with this path is that the Playwright CLI already has a complete capability surface. No matter how comprehensive the abstraction layer’s mapping is, options are inevitably missed, and the actual scope of tools available to the Agent depends on the wrapper author.

In DSH (DeepSeek Harness), “everything is a plugin,” and all tools visible to the model come from plugin registration. Thus, another approach emerged: registering a pass-through tool to hand over the parameters given by the Agent directly to the local CLI. mitao-su/dsh-playwright-native is such a plugin; below is an introduction to its positioning, usage, and notes.

What is this

dsh-playwright-native is maintained by mitao-su, current version 0.1.0, MIT license. Its one-sentence positioning is: register the local native Playwright CLI as a DeepSeek Harness pass-through tool (dsh-plugin), executing whatever parameters the Agent inputs exactly as is.

The plugin registers a tool named playwright using ctx.tools.register(defineTool(...)). The core parameter is only args: string[], forwarding it as-is and in order to the local playwright binary. It does not split install/test/show-report into sub-tools and does not perform any parameter mapping—whatever the Agent gives, it runs.

There is a summary of its implementation in the README: The CLI is the capability, ctx.shell is the execution interface, and defineTool + cordis.patch.yml is the registration.

Core Features

  • Register a pass-through tool named playwright: registered via ctx.tools.register(defineTool(...)), parameters are forwarded as-is and in order to the local playwright binary.
  • Execution uses the ctx.shell executor, sourced from the official bash/pwsh tools, automatically gaining sandbox policies, DSH_* environment variables, output truncation, and timeout/abort categorization.
  • Becomes a layer of the profile configuration tree via cordis.patch.yml + dsh.bundle.patch, automatically written to dsh.profile.bundles after dsh plugin add.
  • command is configurable: defaults to playwright, can be changed to npx --no-install playwright to force using the local project copy.
  • timeoutMs is configurable, default 600000 milliseconds; supports workdir parameter (default session workspace) and timeout override.
  • Injects a systemPrompt paragraph (tool:playwright, order 106) to explain tool usage.
  • isConcurrencySafe is set to false: playwright test shares test-results/report directories, concurrency is not allowed.

Installation and Activation

The installation command is as follows; --profile web means writing the plugin to the web profile:

dsh plugin --profile web add github:mitao-su/dsh-playwright-native

This command automatically writes the plugin to the target profile’s dsh.profile.bundles, no need to manually edit configuration files.

There are three prerequisites:

  1. playwright command is installed locally, playwright --version runs successfully;
  2. dsh is available (the tutorial in the README is verified on 0.1.0-rc.6), and the target profile has the shell executor mounted (standard web/headless profiles come with this);
  3. dsh plugin add depends on pnpm; note that pnpm ≥ 10 intercepts build scripts for Git dependencies by default.

You can verify the environment with two commands before and after installation:

playwright --version     # e.g., Version 1.62.1
dsh --version            # e.g., 0.1.0-rc.6

Default configuration can be used directly. To change the command or timeout, modify the config in the plugin’s cordis.patch.yml:

- insert:
    - id: playwright-native
      name: dsh-playwright-native
      config:
        command: playwright        # Can be changed to "npx --no-install playwright" to force using the local project copy
        timeoutMs: 600000          # Default timeout for each call (milliseconds)

Note: The config here is a full replacement rather than a deep merge; when overriding, you need to restate the required keys.

Typical Usage

After registration, the tool name seen by the Agent is playwright, with a call parameter example:

["test", "tests/", "--reporter", "html"]

The actual execution is playwright test tests/ --reporter html.

Native commands that can be passed through directly include playwright test, playwright install, playwright show-report, playwright --version. You can also pass workdir (default session workspace) and timeoutMs (timeout override) during calls.

Two behavioral details are worth noting:

  • Non-zero exit codes are treated as reports rather than errors; results are tagged with [exit code: N], leaving the next step to the model to decide;
  • When sandboxed, results are tagged with [sandbox: file access denied ...]. You can go through the permission escalation exit point via sandbox_permissions + justification to retry with a wider mode, triggering a prompt for approval before execution.

If you want to modify the code, local building only requires two steps, producing lib/index.js and lib/index.d.ts:

pnpm install
pnpm build        # tsc → lib/index.js + lib/index.d.ts

Applicable Scenarios and Notes

Suitable for developers already using DSH who want the Agent to use the local Playwright according to command-line habits, especially in e2e testing workflows: they don’t want to maintain a mapping from CLI options to a custom schema and are willing to let the Agent face native commands directly.

Note the following points before use:

  1. Sandbox limitations: playwright test will fork worker subprocesses, and playwright install will download browsers, which may be rejected by the file sandbox; you need to go through the permission escalation exit mentioned above.
  2. Security check: The plugin runs with the current dsh process permissions. It is recommended to read the source code and license (this plugin is MIT) before installation to ensure there are no issues before connecting.
  3. Version matching: The plugin version is 0.1.0, and peerDependencies target the DSH/Cordis runtime (e.g., @deepseek-ai/dsh-agent ^0.1.0-rc.6), the tutorial in the README is verified on dsh 0.1.0-rc.6.

Conclusion

The value of dsh-playwright-native lies in restraint: in DSH, all tools visible to the model come from plugin registration; this plugin only does registration and forwarding, leaving the rest to the existing local playwright CLI, not rewriting capabilities and not standing between the Agent and the command.

  • GitHub Repository: https://github.com/mitao-su/dsh-playwright-native
  • Community Directory Page: https://www.skillhub.cn/plugins/mitao-su/dsh-playwright-native (A community-maintained independent directory site with no official affiliation with DeepSeek / Hypersphere)