EJBED Runner

Local execution agent for EJBED — runs your test suites directly on your machine and reports structured results back to the EJBED dashboard.

Supports four test types out of the box: API tests, Security tests, Performance (k6), and UI tests (Playwright).

Requirements

• Node.js 18+ — download here
• An EJBED account at ejbed.com
• The test frameworks you intend to run must already be installed locally (Maven, k6, Python, .NET, etc.)

Installation

npm install -g @ejbed/runner

The installer automatically downloads the Chromium browser needed for UI recording and replay. This may take a minute on first install.

Linux only: if UI recording fails with a missing library error, run npx playwright install-deps chromium (requires sudo).

Quick start

Step 1 — Create a runner token

1. Log in to EJBED → Account Settings → API Keys
2. Click Create token, give it a label (e.g. my-laptop)
3. Copy the token — it starts with ejbed_ and is shown once only

Step 2 — Connect the runner

ejbed-runner login --token ejbed_your_token_here

Saves credentials to ~/.ejbed/runner.json. Do this once per machine.

Step 3 — Start the runner

ejbed-runner start        # background (recommended)
ejbed-runner status       # confirm it's running
ejbed-runner stop         # shut it down
ejbed-runner --watch      # foreground (useful for debugging)

Once started, the runner polls EJBED every 5 seconds for pending jobs. Trigger a run from the EJBED web app — results appear in the Reports dashboard automatically.

What the runner handles

All job types are queued from the EJBED web UI. The runner picks them up and sends structured results back to the dashboard.

| Test type | Frameworks | What you see in the dashboard | |-----------|-----------|-------------------------------| | API tests | Maven/TestNG, JUnit, PyTest, .NET/xUnit, Karate | Per-test-case pass/fail table, failure messages, total counts | | Security tests | Any API framework in security mode | OWASP-categorized results, pass/fail breakdown | | Performance (k6) | k6 | Avg/p95 latency, throughput (req/s), error rate, max VUs, checks | | UI recording | Playwright codegen | Saved Playwright script, detected scenario type, generated test variants | | UI test run | Playwright | Per-variant pass/fail, screenshots on failure, test step detail | | Custom shell | Any command | Exit code, full stdout/stderr |

Supported frameworks

| Framework | Run command (enqueued from UI) | Report source | |-----------|-------------------------------|---------------| | Maven + TestNG / JUnit | mvn test | target/surefire-reports/TEST-*.xml | | Maven + Karate DSL | mvn test -Dtest=KarateRunner | target/surefire-reports/TEST-*.xml | | Gradle + TestNG / JUnit | gradle test | build/test-results/test/*.xml | | Python + PyTest | pytest --junitxml=report.xml | report.xml | | .NET + xUnit / NUnit | dotnet test --logger "junit;LogFilePath=TestResults.xml" | TestResults.xml | | k6 Performance | k6 run k6-project/main.js | Parsed from k6 stdout (avg/p95 latency, error rate, throughput) | | Playwright (UI) | Triggered via UI recording / run buttons | Playwright JSON reporter → pass/fail per variant | | Custom | Any shell command | stdout/stderr captured, exit code recorded |

k6 note: the runner captures k6's terminal output and the backend automatically extracts performance metrics (avg latency, p95, throughput, error rate, max VUs). No extra flags or file exports are needed — just run k6 run.

Configuration

After login, config lives in ~/.ejbed/runner.json. Override any value with environment variables or a runner/.env file (KEY=VALUE per line).

| Variable | Default | Description | |----------|---------|-------------| | EJBED_API_URL | https://ejbed.com | EJBED API base URL | | EJBED_RUNNER_TOKEN | (from login) | Runner auth token (ejbed_…) | | EJBED_POLL_INTERVAL_MS | 5000 | Milliseconds between job polls | | EJBED_HEADLESS | 0 | Set to 1 to run UI tests without a visible browser window | | EJBED_PW_WORKERS | 1 | Playwright parallel workers (max 8) | | EJBED_PW_RETRIES | 0 | Playwright retry count for flaky tests (max 3) |

Self-hosted / local dev:

ejbed-runner login --token ejbed_xxx --url http://localhost:5000

CLI reference

ejbed-runner login --token <ejbed_…> [--url <api-url>]
    Save credentials for this machine.

ejbed-runner start
    Start the runner in the background (writes PID + logs to ~/.ejbed/).

ejbed-runner stop
    Stop the background runner.

ejbed-runner status
    Show whether the runner is running and which API it is connected to.

ejbed-runner logs
    Print the last 100 lines from ~/.ejbed/runner.log.

ejbed-runner --watch / -w
    Run in the foreground, polling continuously. Useful for debugging.

ejbed-runner (no args)
    Claim and execute one pending job, then exit. Useful in CI scripts.

Troubleshooting

Runner says "No pending runs" and exits → Normal for the no-arg mode. Use ejbed-runner start so it keeps polling in the background, or --watch for foreground continuous polling.

"Missing EJBED_RUNNER_TOKEN" → Run ejbed-runner login --token ejbed_xxx first, or set EJBED_RUNNER_TOKEN in the environment.

"Token looks like a SHA-256 hash" → You copied the wrong value. The token starts with ejbed_ (not a 64-char hex string). Create a new token in the UI — the plaintext is only shown at creation time.

k6 run shows no metrics in the dashboard → Make sure k6 is installed and on your PATH (k6 version). The backend parses k6 metrics from stdout automatically — no extra flags needed.

UI recording: browser opens but nothing is recorded → The runner must be running on the same machine as your browser. Playwright's codegen only captures interactions from that local browser session.

Linux: "error while loading shared libraries" → Run npx playwright install-deps chromium to install OS-level browser dependencies (requires sudo).

Windows: runner won't stop → Run ejbed-runner stop in the same shell (or as Administrator), or kill the process from Task Manager using the PID shown by ejbed-runner status.

Run stays in "Queued" state → The runner is not polling. Check ejbed-runner status. Common causes: wrong EJBED_API_URL, revoked/mismatched token, or a firewall blocking outbound HTTPS.

JUnit report not found after test run → Verify the junit_report_path matches where your framework writes the file. Use glob patterns for Maven (e.g. target/surefire-reports/TEST-*.xml).

Security

• The runner executes shell commands with your local user's permissions. Only install the runner on machines you control.
• Runner tokens are stored as SHA-256 hashes on the server — the plaintext is never logged or persisted.
• Credentials (JWT tokens, API keys, passwords) are automatically masked in logs before being stored.
• Revoke a token immediately from Account Settings → API Keys if a machine is lost or compromised.
• The runner signals graceful shutdown to the server on SIGTERM/SIGINT — it marks itself offline so the dashboard reflects the correct state.