GraphWalker is a model-based testing tool. It reads models in the shape of directed graphs and generates test paths from them. Tests are modeled as graphs where vertices represent states and edges represent transitions between states. GraphWalker traverses these graphs using configurable path generators and stop conditions, producing sequences of steps that can drive automated test execution.
GraphWalker supports guards (boolean conditions on edges), actions (scripts that run on traversal), requirements tracking, weighted edges, shared states across multiple models, and several path generation algorithms ranging from pure random walks to optimal Chinese Postman routes.
- Rust (1.88 or later) — install via rustup
- Git
- Node.js and npm (only needed if building the Studio frontend from source)
If you have the Nix package manager installed, you don't need to manually install Rust or Node.js. A fully configured developer environment is provided via flakes.
Simply run:
nix developThis automatically boots a shell with rustc, cargo, rustfmt, clippy, rust-analyzer, nodejs, and all required libraries configured.
If you use direnv, you can automate this by running:
echo "use flake" > .envrc && direnv allow# Clone the repository
git clone https://github.com/GraphWalker/graphwalker-rs.git
cd graphwalker-rs
# Build all crates (debug)
cargo build
# Build optimized release binaries
cargo build --release
# Run tests
cargo testThe main binaries are:
| Binary | Location | Description |
|---|---|---|
graphwalker |
target/release/graphwalker |
CLI tool for offline/online test generation |
graphwalker-studio |
target/release/graphwalker-studio |
Web-based visual model editor and test runner |
graphwalker-mcp |
target/release/graphwalker-mcp |
Local MCP server for model authoring, validation, conversion, and execution |
# Check a model for issues
graphwalker check -g model.json
# Generate a test path offline
graphwalker offline -m model.json "random(edge_coverage(100))"
# Start a REST API server
graphwalker online -s RESTFUL -p 8080 -m model.json "random(edge_coverage(100))"
# Start the visual Studio
graphwalker-studio
# Start the local MCP server (normally launched by an MCP client)
graphwalker-mcpInstall only the MCP server from a checkout with cargo install --locked --path graphwalker-mcp, then configure an MCP client to launch graphwalker-mcp over stdio. See the MCP Server guide for client configuration and a complete model-authoring workflow.
The MCP server selects one model element at a time; the MCP client or its test adapter performs edge actions and verifies vertex states in the system under test. Drafts and executions are process-local, so export canonical JSON before disconnecting when a model must persist.
Full documentation is available at graphwalker.github.io/graphwalker-rs.
- What is Model-Based Testing
- Getting Started
- CLI Reference
- Generators and Stop Conditions
- JSON Model Format
- REST API
- WebSocket API
- GraphWalker Studio
- MCP Server
The documentation site is built with Jekyll. To run it with Docker from the repository root:
docker run --rm -it \
--user "$(id -u):$(id -g)" \
-e HOME=/tmp \
-p 4000:4000 \
-v "$PWD:/workspace" \
-w /workspace/doc \
ruby:3.3-bookworm \
sh -lc 'bundle config set --local path vendor/bundle && bundle install && bundle exec jekyll serve --host 0.0.0.0 --baseurl ""'Without Docker, install Ruby and Bundler first. On Ubuntu or Debian:
sudo apt update
sudo apt install ruby-full build-essential zlib1g-dev
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
gem install bundlerOn macOS, install Ruby with brew install ruby, add Homebrew's Ruby to your PATH, and install Bundler with gem install bundler.
Then run the site from the repository root:
cd doc
bundle config set --local path vendor/bundle
bundle install
bundle exec jekyll serve --baseurl ""Open http://localhost:4000 in a browser. Jekyll rebuilds the site when documentation files change; stop the server with Ctrl+C.
MIT