This PR adds a powerful testui command with flexible argument parsing and comprehensive Z.ai setup documentation.

# Natural language testing
testui PROMPT="login with [email protected]"

# YAML test file execution  
testui TEST="tests/login.yaml"

# External app testing
testui APP="http://localhost:3000" PROMPT="test checkout flow"

# Shorthand (positional)
testui "click all buttons"

Key Features:

• ✅ PROMPT="text" - Natural language test execution
• ✅ TEST="file.yaml" - YAML test file execution
• ✅ APP="url" - Test external applications
• ✅ Positional argument support (shorthand syntax)
• ✅ Automatic ANTHROPIC_API_KEY validation
• ✅ Built-in help command (--help, -h)
• ✅ Proper error handling and cleanup
• ✅ External app testing capability

• View current page context for debugging
• Helps understand page structure during test development

# Step 1: Clone & Install
git clone https://github.com/Zeeeepa/cli.git
cd cli/testdriver-proxy
npm install

# Step 2: Get Z.ai API Key (Free)
Visit https://z.ai and sign up

# Step 3: Configure
export ANTHROPIC_API_KEY="your-zai-api-key"
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.bashrc

# Step 4: Test It!
testui PROMPT="login with [email protected]"

Documentation Improvements:

• ✅ Z.ai API key setup instructions
• ✅ ANTHROPIC_API_KEY environment variable explained
• ✅ Complete usage examples for all scenarios
• ✅ Persistence configuration (bashrc/zshrc)
• ✅ All command variations documented

• ✅ Validates ANTHROPIC_API_KEY before starting tests
• ✅ Clear error messages if API key is missing
• ✅ Proper cleanup on errors and interrupts
• ✅ Handles external app testing gracefully
• ✅ Built-in help documentation

server.js:

• Enhanced error handling
• Better request/response validation
• Structured logging
• Timeout handling
• Graceful degradation

• testdriver-proxy/bin/testui (NEW) - Main test command
• testdriver-proxy/bin/context (NEW) - Debug helper
• testdriver-proxy/README.md - Complete rewrite with setup guide
• testdriver-proxy/server.js - Enhanced robustness
• testdriver-proxy/package.json - Updated scripts
• testdriver-proxy/.env.example - Updated configuration

Tested with:

• ✅ Z.ai API (GLM-4.5V model)
• ✅ PROMPT argument parsing
• ✅ TEST file execution
• ✅ APP external URL testing
• ✅ Error handling (missing API key)
• ✅ Help command
• ✅ Cleanup on errors and interrupts

# Basic testing (auto-starts test app on port 4000)
testui PROMPT="click all buttons and verify"
testui PROMPT="login with [email protected]"

# Test file execution
testui TEST="path/to/test.yaml"
testui TEST="tests/login-flow.yaml"

# External app testing
testui APP="http://localhost:3000" PROMPT="test checkout"
testui APP="https://myapp.com" PROMPT="verify homepage"

# Shorthand
testui "click the signup button"

Ready for review and testing! 🎯

Automate and scale QA with computer-use agents.

Docs | Website | GitHub Action | Join our Discord

Follow the instructions on our docs for more..

TestDriver isn't like any test framework you've used before. TestDriver is an OS Agent for QA. TestDriver uses AI vision along with mouse and keyboard emulation to control the entire desktop. It's more like a QA employee than a test framework. This kind of black-box testing has some major advantages:

• Easier set up: No need to add test IDs or craft complex selectors
• Less Maintenance: Tests don't break when code changes
• More Power: TestDriver can test any application and control any OS setting

• Test any user flow on any website in any browser
• Clone, build, and test any desktop app
• Render multiple browser windows and popups like 3rd party auth
• Test <canvas>, <iframe>, and <video> tags with ease
• Use file selectors to upload files to the browser
• Test chrome extensions
• Test integrations between applications
• Integrates into CI/CD via GitHub Actions ($)

Check out the docs.

1. Tell TestDriver what to do in natural language on your local machine using npm i testdriverai -g
2. TestDriver looks at the screen and uses mouse and keyboard emulation to accomplish the goal
3. Run TestDriver tests on our test infrastructure

In your project directory:

npx testdriverai@latest init

Let's show TestDriver what we want to test. Run the following command:

npx testdriverai@latest .testdriver/test.yaml

TestDriver best practice is to start instructing TestDriver with your app in it's initial state. For browsers, this means creating a new tab with the website you want to test.

If you have multiple monitors, make sure you do this on your primary display.

Now, just tell TestDriver what you want it to do. For now, stick with single commands like "click sign up" and "scroll down."

Later, try to perform higher level objectives like "complete the onboarding."

> Click on sign up
TestDriver Generates a Test
TestDriver will look at your screen and generate a test script. TestDriver can see the screen, control the mouse, keyboard, and more!
TestDriver can only see your primary display!
To navigate to testdriver.ai, we need to focus on the
Google Chrome application, click on the search bar, type
the URL, and then press Enter.

Here are the steps:

1. Focus on the Google Chrome application.
2. Click on the search bar.
3. Type "testdriver.ai".
4. Press Enter.

Let's start with focusing on the Google Chrome application
and clicking on the search bar.

commands:
  - command: focus-application
    name: Google Chrome
  - command: hover-text
    text: Search Google or type a URL
    description: main google search
    action: click

After this, we will type the URL and press Enter.

TestDriver will execute the commands found in the yml codeblocks of the response.

See the yml TestDriver generated? That's our own schema. You can learn more about it in the reference.

Take your hands off the mouse and keyboard while TestDriver executes! TestDriver is not a fan of backseat drivers.

Feel free to ask TestDriver to perform some more tasks. Every time you prompt TestDriver it will look at your screen and generate more test step to complete your goal.

> navigate to airbnb.com
> search for destinations in austin tx
> click check in
> select august 8

If something didn't work, you can use /undo to remove all of the test steps added since the last prompt.

Now it's time to make sure the test plan works before we deploy it. Use testdriver run to run the test file you just created with /save .

npx testdriverai@latest run testdriver/test.yaml

Make sure to reset the test state!

Now it's time to deploy your test using our GitHub action! testdriver init already did the work for you and will start triggering tests once you commit the new files to your repository.

git add .
git commit -am "Add TestDriver tests"
gh pr create --web

Your test will run on every commit and the results will be posted as a Dashcam.io video within your GitHub summary! Learn more about deploying on CI here.

TestDriver can also be used programmatically as a Node.js module. This is useful when you want to integrate TestDriver into your own applications or customize the test file paths.

By default, TestDriver looks for test files at testdriver/testdriver.yaml relative to the current working directory. You can customize this:

const TestDriverAgent = require("testdriverai");

// Option 1: Set default via environment variable
const agent1 = new TestDriverAgent({
  TD_DEFAULT_TEST_FILE: "my-tests/integration.yaml",
});

// Option 2: Explicitly specify test file
const agent2 = new TestDriverAgent(
  {},
  {
    args: ["path/to/specific/test.yaml"],
  },
);

// Option 3: Custom working directory + relative path
const agent3 = new TestDriverAgent(
  { TD_DEFAULT_TEST_FILE: "tests/smoke.yaml" },
  { options: { workingDir: "/path/to/your/project" } },
);

// Run the test
await agent1.run();

You can also set the default test file path using environment variables:

export TD_DEFAULT_TEST_FILE="custom/path/test.yaml"
node your-script.js