skills.rest
cockroachdb
cockroachdbOFFICIAL
Explore all skills by this author →
WebsiteGitHub

run-roachtest

Launches a single CockroachDB roachtest locally or on a GCE worker via detached tmux with completion notification.

32.4k|4.1k|Updated Feb 6, 2014
Search Tags:#Testing#gce#cockroachdb#roachtest#distributed-database#Tmux#roachdev
One-click install
npx skills add https://github.com/cockroachdb/cockroach --skill run-roachtest
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: run-roachtest
Source: https://github.com/cockroachdb/cockroach/tree/main/.claude/skills/run-roachtest
Command: npx skills add https://github.com/cockroachdb/cockroach --skill run-roachtest

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Running a CockroachDB roachtest involves error-prone decisions: choosing local vs. remote execution, launching on a GCE worker so the run survives a closed laptop, and getting notified when a long test finishes. This Skill automates that entire workflow correctly.

Core Features & Use Cases

  • Local vs. remote decisioning: Inspects the test source for Linux-only mechanics, heavy cluster specs, or local-mode bypasses to pick the right execution target.
  • Detached remote execution: Launches roachstress.sh inside a detached tmux session on the user's GCE worker via roachdev worker ssh, with unique session, log, and signal names to avoid collisions with concurrent runs.
  • Long-poll completion notification and live tail: Uses tmux wait-for semaphores and background tail -F tasks so the user gets one notification at the end and can peek at live progress anytime.
  • Use Case: You just modified a roachtest under pkg/cmd/roachtest/tests/ and want to run it on your GCE worker; the Skill pushes your branch, syncs the worker checkout, launches the test detached, and reports pass/fail with artifact paths when done.

Quick Start

Run the acceptance/build-info roachtest on my GCE worker and notify me when it finishes.

Frequently Asked Questions about run-roachtest

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a CockroachDB roachtest on a GCE worker?▼

Push your branch to your fork, fetch and reset it on the worker via roachdev worker ssh, then launch roachstress.sh inside a detached tmux session. The Skill adds a tmux wait-for signal so a background task notifies you when the run finishes.

How do I decide between running a roachtest locally or remotely?▼

Follow the user's explicit wording first. Otherwise inspect the test source: Linux-only mechanics like cgroups or iptables and heavy multi-node clusters require the remote worker, while acceptance tests and tests with a c.IsLocal() bypass can run locally.

Can I run a roachtest while another roachstress run is in progress?▼

Yes, but only after confirming the in-progress run is past its build phase, since switching branches mid-build corrupts it. Check for dev build processes, cached binaries under artifacts/<sha>/, and an existing test.log before touching the checkout.

Why use roachstress.sh instead of ./dev test for roachtests?▼

roachstress.sh cross-compiles cockroach, workload, and roachtest binaries for the cluster architecture and caches them by SHA. ./dev test is for unit tests and does not produce the binaries a roachtest cluster needs.

Where are roachtest artifacts stored after a run?▼

Artifacts live at ~/go/src/github.com/cockroachdb/cockroach/artifacts/<sha>/<runid>/<test-name>/run_1/ on the worker. Key files include test.log, per-node perf stats.json, and phases.json for perturbation tests, downloadable via roachdev worker scp.

Related Skills

Explore More Software Engineering Skills→
cockroachdbcockroachdb
32.4k

reduce-unoptimized-query-oracle

Reduce CockroachDB roachtest failure logs to minimal SQL reproduction scripts.

Official
Advanced
cockroachdbcockroachdb
32.4k

engflow-artifacts

Download Engflow CI build artifacts and inspect failed CockroachDB test targets.

Official
Intermediate
grafanagrafana
213

cost-management

Manage Grafana Cloud costs with label-based attribution and usage alerts.

Official
Intermediate
DojoGenesisDojoGenesis
2

build-sweep

Detect and fix failing Go builds and tests across multi-module workspaces.

Community
Advanced