Install Testver

This page walks you through getting Testver up and running. It assumes zero prior knowledge. By the end, you’ll have the Testver UI open in your browser at http://localhost:3700.

Introduction

Testver is an AI-powered test-automation dashboard. It scans your test project, runs your tests, shows results with screenshots and step-by-step details, helps you record and fix tests, and can schedule runs — all from a web dashboard in your browser.

What this guide covers. Everything you need to install and run Testver from the official npm package — the prerequisites, the exact software to install, a local setup on your own computer, and a shared server setup for a whole team. Every step is written so that someone with no prior experience can follow it.

How Testver is delivered. Testver is published on the npm registry as @testver/testver. You install it once with a single command and then run it. Docker is optional and is NOT required for any setup in this guide.

Note

Throughout this document, anything shown in a shaded box is a command you type into a terminal (Command Prompt / PowerShell on Windows, or Terminal on macOS/Linux). Type it exactly, then press Enter.

Key Terms (Plain English)

If any of the words below are new to you, read this short list first. You do not need to memorise it — just refer back when needed.

Term	What it means
Terminal	A text window where you type commands. On Windows it is “Command Prompt” or “PowerShell”; on macOS/Linux it is “Terminal”.
Node.js	The runtime (engine) that Testver is built on. You must install it first. Testver needs version 20 or newer.
npm	The “Node Package Manager”. It comes bundled with Node.js and is used to install Testver.
package	A piece of software published online that npm can download and install. Testver is one such package.
global install	Installing a tool so it can be run from anywhere on your computer (used for command-line tools like Testver).
dashboard	The Testver web page you open in your browser to see and control everything.
port	A numbered “door” on a computer that a program listens on. Testver uses 3700 by default (e.g. http://localhost:3700).
localhost	A name that means “this computer”. http://localhost:3700 opens Testver running on your own machine.
API key	A secret password-like string from an AI provider (e.g. Anthropic/OpenAI) that lets Testver use AI features.

Prerequisites & Required Software

Before installing Testver, the following must be present on the machine. Items 1–2 are mandatory for everyone. Items 3–5 depend on what kind of tests you run.

Mandatory for everyone

#	Software	Version	Why it is needed
1	Node.js	20.0.0 or newer	The engine Testver runs on. Installing Node also installs npm.
2	npm	Comes with Node	Used to download and install the Testver package.

Minimum hardware: any modern laptop/desktop with at least 4 GB RAM (8 GB+ recommended) and ~2 GB free disk space.

Needed depending on your tests

If your tests use…	You also need to install	Notes
Playwright, Cypress, Jest, Mocha, WebdriverIO (JavaScript/TypeScript)	Node.js (already covered) + the browser binaries	Browsers are installed with one command — see Section 4.4.
pytest (Python)	Python 3.8+ and pip	Install from python.org or your OS package manager.
JUnit / TestNG (Java)	Java JDK 11+ and Maven or Gradle	Required so Testver can run the Java tests.
NUnit / xUnit / MSTest (.NET)	.NET SDK 6.0+	Install from dotnet.microsoft.com.
RSpec (Ruby)	Ruby 3.0+	Install from ruby-lang.org or your OS package manager.

Note

Testver does not install your test framework or its language runtime. It runs the tests that already work in your project. So if your project is, say, a pytest project, Python and the project’s dependencies must be installed and working first.

Needed for AI features

Testver’s AI features (recording, fixing, chat) need an API key from at least one AI provider. You can use Testver to run and view tests WITHOUT a key, but AI features stay disabled until you add one.

• Anthropic (Claude) — recommended. Get a key at console.anthropic.com.
• OpenAI (GPT) — get a key at platform.openai.com.
• Google (Gemini), xAI (Grok), or local models via Ollama / LM Studio are also supported.

Local Setup (Your Own Computer)

Follow these steps in order on the computer where you want to use Testver. This is the right choice for a single developer/tester.

Step 1 — Install Node.js (version 20+)

Windows:

1. Open a web browser and go to https://nodejs.org

2. Download the “LTS” version (the big green button). LTS means “Long-Term Support” — the stable one.

3. Run the downloaded installer and click Next/Agree until it finishes. Leave all options at their defaults. macOS:

4. Go to https://nodejs.org and download the LTS “macOS Installer (.pkg)”, then run it; OR, if you use Homebrew, run the command below.

brew install node

Linux (Ubuntu/Debian):

# Install Node.js 20 LTS from NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Step 2 — Verify Node and npm are installed

Open a new terminal window and run these two commands. Each should print a version number.

node --version
npm --version

You should see something like v20.11.0 and 10.2.4. If the Node version is below 20, install the LTS version again from Section 4.1.

Caution

If you see “node is not recognized” (Windows) or “command not found” (macOS/Linux), close the terminal, open a brand-new one, and try again. The installer’s changes only apply to newly-opened terminals.

Step 3 — Install Testver

Run this single command. The -g means “global”, so the testver command works from any folder.

npm install -g @testver/testver

macOS/Linux permission errors? If you see an EACCES or “permission denied” error, either re-run with sudo npm install -g @testver/testver, or (better) use a Node version manager such as nvm so global installs don’t need admin rights.

Verify the install:

testver --version

It should print the version, e.g. testver v1.0.0.

Caution

Always install with -g (global). If you run “npm install @testver/testver” WITHOUT -g, it only downloads the package into the current folder and the “testver” command will NOT work globally. To run a local (non-global) install you would have to use “npx testver”.

Step 4 — Install browser binaries (for web UI tests)

If your tests drive a real browser (Playwright/Cypress/Selenium/WebdriverIO), install the browsers once:

npx playwright install

Step 5 — Start Testver

In your terminal, move into your test project’s folder, then start the dashboard server:

# Windows example
cd C:\path\to\your\test-automation-framework

# macOS/Linux example
cd /path/to/your/test-automation-framework

# Start the dashboard
testver serve

You will see a banner that says the server is running, with a line like Local: http://localhost:3700.

Note

“testver serve” runs the dashboard in the background and keeps it open until you press Ctrl+C. You can also run plain “testver” (no “serve”) for the interactive command-line mode, but for the dashboard use “serve”.

Step 7 — Open the dashboard and create your account

1. Open your web browser and go to: http://localhost:3700
2. The first time, Testver shows a one-time Setup screen. Create your admin account (username + a strong password). This account is yours; keep the password safe.
3. After setup, you land on the dashboard. Testver auto-detects your framework and lists your tests. You are ready to run tests.

Caution

The very first person to open a fresh Testver instance creates the admin account. On your own computer (localhost) this is fine. On a shared server, complete this setup immediately after starting the server (see Section 5).

Server Setup for a Team (Self-Hosted)

This section hosts the Testver dashboard on one always-on machine (a server) so your whole team can open it in their browsers. No Docker is required — the npm package runs the same dashboard; we just keep it running and put it behind a secure address.

You will: (1) prepare a Linux server, (2) install Node + your test toolchain, (3) install Testver, (4) keep it running with a service manager, (5) put it behind HTTPS, and (6) lock down access.

Step 1 — Choose and prepare a server

• A Linux server (Ubuntu 22.04 LTS is a good default) — a cloud VM (AWS/Azure/GCP/DigitalOcean) or an on-premise machine.
• At least 2 CPU cores and 4 GB RAM (8 GB+ if many tests run at once).
• SSH access to the server, and a user with sudo (admin) rights.
• Optional but recommended: a domain name (e.g. testver.yourcompany.com) pointed at the server’s IP address, for HTTPS.

Step 2 — Install Node.js and your test toolchain on the server

# Update the system
sudo apt-get update && sudo apt-get upgrade -y

# Install Node.js 20 LTS + git
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git

# Verify
node --version
npm --version

# Install Browsers
npx playwright install --with-deps chromium

Then install whatever your tests need on the SAME server (only the ones you use):

Note

The server must be able to run your tests on its own. Install the same language runtimes and project dependencies you use locally.

Step 3 — Install Testver on the server

sudo npm install -g @testver/testver
testver --version

Step 4 — Put your test automation framework on the server

Copy your test framework onto the server (for example with git):

cd /srv
sudo git clone https://github.com/your-org/your-test-framework.git
cd your-test-framework
# install the project’s own dependencies, e.g.:
npm install        # for JS/TS projects
# or: pip install -r requirements.txt   (Python)

Step 5 — Keep Testver running as a background service

A server should keep Testver running and restart it automatically after a crash or reboot. Two common ways — pick ONE.

Option A — systemd (recommended on Linux)

Create a service file:

sudo nano /etc/systemd/system/testver.service

Paste the following (adjust the paths, user, and API key):

[Unit]
Description=Testver Dashboard
After=network.target

[Service]
Type=simple
WorkingDirectory=/srv/your-test-project
ExecStart=/usr/bin/testver serve --host 127.0.0.1 --port 3700
Environment=NODE_ENV=production
Environment=ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
Environment=TESTVER_DEFAULT_PROVIDER=anthropic
Restart=always
RestartSec=5
User=testver

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable testver
sudo systemctl start testver

# Check status and logs
sudo systemctl status testver
journalctl -u testver -f

Note

We bind to 127.0.0.1 (localhost on the server) on purpose. In Step 6 a reverse proxy will safely expose it to your team over HTTPS. Binding directly to 0.0.0.0 would expose the unencrypted dashboard to the network.

Option B — pm2 (Node process manager)

sudo npm install -g pm2
cd /srv/your-test-project
ANTHROPIC_API_KEY=sk-ant-xxx pm2 start "testver serve --host 127.0.0.1 --port 3700" --name testver
pm2 save
pm2 startup     # run the command it prints, to start on boot

Step 6 — Add HTTPS with a reverse proxy (Nginx)

A reverse proxy gives your team a clean, secure https:// address and handles encryption. Testver uses WebSockets for live updates, so the proxy must forward the Upgrade headers (shown below).

sudo apt-get install -y nginx
sudo nano /etc/nginx/sites-available/testver

Paste this (replace testver.yourcompany.com with your domain):

server {
    listen 80;
    server_name testver.yourcompany.com;

    location / {
        proxy_pass http://127.0.0.1:3700;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}

Enable the site and add a free HTTPS certificate with Let’s Encrypt:

sudo ln -s /etc/nginx/sites-available/testver /etc/nginx/sites-enabled/
sudo nginx -t        # test the config
sudo systemctl reload nginx

# Free HTTPS certificate (auto-renews)
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d testver.yourcompany.com

Your team can now open https://testver.yourcompany.com.

Step 7 — Create the admin account immediately

Open the HTTPS address in a browser and complete the one-time Setup screen RIGHT AWAY to create the admin account. Then add accounts for your teammates from the dashboard.

Caution

Until an admin account exists, a fresh Testver instance is unconfigured and the first visitor becomes admin. On a public/shared server, do this setup before sharing the link, or restrict access (Section 6) first.

Step 8 — Restrict who can reach it

Because Testver can run commands on the server, treat access as you would shell access. Choose at least one:

• Keep it on the company network / VPN (e.g. Tailscale, WireGuard) so only employees can reach it.
• Add an IP allow-list in Nginx, or put a single-sign-on (SSO) proxy in front (e.g. Cloudflare Access).
• Open only the needed ports in the server firewall:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Security Checklist (Read Before Exposing to a Network)

Testver executes your test commands on the host. Anyone who can sign in can effectively run programs on that machine, so protect it accordingly.

• Create the admin account immediately after first start; use strong, unique passwords.
• Never expose the dashboard directly to the public internet without HTTPS and access control (VPN/SSO/IP allow-list).
• Bind the app to 127.0.0.1 and let the reverse proxy handle public traffic (do not bind 0.0.0.0 directly to the internet).
• Keep API keys and credentials only in the server’s environment/.env — never commit them to git.
• Run the service as a non-root user (the systemd example uses User=testver).
• Keep Testver updated (Section 8) — fixes ship frequently.

Note

Testver is a single-team, self-hosted tool — one instance serves one project/team. It is not a multi-tenant public service. Each team should run its own protected instance.

Configuration Reference (Environment Variables)

Set these in a .env file in your project folder, or as environment variables in your shell / service file.

Server settings

Variable	Default	Purpose
TESTVER_HOST	localhost	Network address to bind. Use 0.0.0.0 only behind a proxy/VPN.
TESTVER_PORT	3700	Port the dashboard listens on.

AI provider keys

Variable	Purpose
ANTHROPIC_API_KEY	Anthropic (Claude) API key.
OPENAI_API_KEY	OpenAI (GPT) API key.
GOOGLE_API_KEY	Google (Gemini) API key.
XAI_API_KEY	xAI (Grok) API key.
TESTVER_DEFAULT_PROVIDER	Which provider to use by default: anthropic, openai, google, xai, ollama, or lmstudio.
TESTVER_DEFAULT_MODEL	Optional. Override the model used for the default provider.

Optional model overrides

Variable	Default
ANTHROPIC_MODEL	claude-sonnet-4-20250514
OPENAI_MODEL	gpt-4o
GOOGLE_MODEL	gemini-2.0-flash
XAI_MODEL	grok-2-latest
OLLAMA_BASE_URL	http://localhost:11434/v1
LMSTUDIO_BASE_URL	http://localhost:1234/v1

Updating, Verifying & Uninstalling

Check the running version

testver --version

Update to the latest version

npm install -g @testver/testver@latest

On a server, restart the service after updating:

sudo systemctl restart testver     # systemd
# or
pm2 restart testver                # pm2

Health check (is it running?)

Testver exposes a health endpoint. From the server (or your machine) run:

curl http://localhost:3700/api/health

A healthy server returns a small JSON response with “status”: “healthy” and the version.

Uninstall

npm uninstall -g @testver/testver

Troubleshooting (Common Problems)

Problem	Cause & Fix
”testver: command not found” or “not recognized”	You installed without -g, or the terminal is stale. Run: npm install -g @testver/testver, then open a NEW terminal. As a fallback, run it with: npx @testver/testver serve
Node version error / very old features	Node is below 20. Run node —version; if under 20, reinstall the LTS version from nodejs.org.
”EADDRINUSE” / port 3700 already in use	Another program (or a previous Testver) holds the port. Start on a different port: testver serve —port 8080
”EACCES” / permission denied on npm install -g	macOS/Linux global installs need rights. Use sudo, or install a Node version manager (nvm) so global installs do not need admin.
”EMFILE: too many open files” on macOS	A very large project hit the file-watch limit. Update to the latest Testver (it self-protects), or run: ulimit -n 10240 before testver serve.
Tests do not run / framework not detected	Make sure the tests run on their own first (e.g. npx playwright test / pytest). The language runtime + project dependencies must be installed on the same machine.
AI features greyed out	No API key configured. Add a provider key to .env (Section 4.5) and restart Testver.
Team cannot reach the server URL	Check the service is running (systemctl status testver), Nginx is reloaded, the firewall allows Nginx, and DNS points to the server.
Live log / dashboard freezes on an 8+ hour run	Update to the latest Testver — long-run output is bounded and the live socket is kept alive in current versions.

Quick Command Reference

Command	What it does
npm install -g @testver/testver	Install Testver globally.
testver —version	Show the installed version.
testver —help	Show all commands and options.
testver	Start interactive command-line mode.
testver serve	Start the web dashboard on http://localhost:3700.
testver serve —port 8080	Start the dashboard on a custom port.
testver serve —host 0.0.0.0	Listen on all network interfaces (use only behind a proxy/VPN).
npx playwright install —with-deps	Install browser binaries for web tests.
npm install -g @testver/testver@latest	Update to the newest version.
curl http://localhost:3700/api/health	Check that the server is healthy.

End of guide. For the full list of options at any time, run testver --help.