# getgauge/gauge: Markdown specs, plugin runners, and a maintenance caveat

> Gauge is a cross-platform test automation tool that keeps specifications in Markdown and pushes step implementations into language-specific plugin runners. The design is sound; the project's own README says the core team can no longer promise the same level of dedication.

**getgauge/gauge** — Light weight cross-platform test automation

- Repository: https://github.com/getgauge/gauge
- Website: https://gauge.org
- Stars: 3,189 · Forks: 355
- Language: Go
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/getgauge-gauge

## What Gauge solves, and who it is actually for

Most test frameworks force a choice: either the tests read like code, or they read like English and drift away from the code that executes them. Gauge takes the second path deliberately. The README describes it as a light weight cross-platform test automation tool that provides the ability to author test cases in the business language. Specifications live in Markdown files, so a product manager can read a scenario without opening an IDE, and the wiring that makes those sentences executable lives in a separate step implementation file.

The audience is narrower than the tagline suggests. Gauge suits teams that already treat acceptance criteria as artefacts and want them versioned next to the code. It suits polyglot organisations, because the runner is a separate process and the step implementations can be written in a different language from the core tool. It does not suit a single developer writing a handful of browser checks in one language; the indirection costs more than it returns at that scale.

## How the Markdown spec reaches a step implementation

The repository layout shows the split clearly. The top level contains parser/, execution/, runner/, plugin/, formatter/, reporter/, validation/ and skel/ alongside cmd/ and gauge.go. The core binary parses specifications, builds an execution plan, and then talks to a language runner over gRPC. The go.mod file lists google.golang.org/grpc and github.com/getgauge/gauge-proto/go/gauge_messages, which is the generated protocol package the core and the runners share.

That protocol boundary is the design decision worth understanding. The core does not execute steps. It hands step text and parameters to the runner, waits for a result, and reports it. Runners are separate installable plugins, which is why the plugin/ directory exists and why the project maintains a separate skeleton tree in skel/ for bootstrapping a new runner. The practical consequence is that a Gauge upgrade and a runner upgrade are two different operations, and a mismatch between them is a failure mode you can create for yourself.

The core also carries a conceptExtractor/ directory and depends on github.com/schollz/closestmatch, which points at how step text is matched and how near-miss suggestions are produced when a step cannot be resolved. When a spec step matches nothing, the closest-match dependency is what lets the tool suggest a similar existing step rather than failing silently. Formatters and reporters are separate trees, so console output, HTML reports and any custom report are pluggable rather than baked into the runner.

## Installing Gauge and running a first specification

The README does not reproduce install commands. It points to the Gauge documentation and to a setup guide in the wiki, so the canonical instructions live at docs.gauge.org and in the wiki rather than in the repository README. What the repository does give you is the build side: go.mod declares module github.com/getgauge/gauge and go 1.26.0, so a source build assumes a Go toolchain at that version.

The README also gives an example of the badge markup you can add to a project that uses Gauge, which is the only literal snippet it prints:

```
[![Gauge Badge](https://gauge.org/Gauge_Badge.svg)](https://gauge.org)
```

That snippet is a README badge, not a command, and it is worth being clear about what the repository does not contain. There is no install command, no scaffold command, no run command and no properties example in the README or in the files listed above. The CLI itself is built from cmd/, which depends on github.com/spf13/cobra, and the project layout includes plugin/, runner/, skel/, config/ and env/ directories, but none of those directories are shown with their contents here, so no subcommand name, flag or configuration key can be quoted from this material.

If you want to try Gauge, the only instruction the README actually gives is to read the setup guide in the wiki and the getting started pages in the documentation. Anything beyond that would be guesswork on my part, and a guessed subcommand is worse than no example at all.

## The maintenance note is the first thing to read

The README opens with an important note rather than a feature list, and it is blunt. Gauge's official sponsorship ended in 2021. The note states that the core team will only look into issues in their spare time, that response times are slower, and that pull requests should expect significant delays in reviewing and merging. It then asks readers to consider using Gauge only if prepared to adopt and support it fully on their own.

That paragraph should shape the adoption decision more than any technical property of the tool. Releases are still being cut, and the last push to the default branch was on 2026-09-16, so the repository is not frozen. But a recent push is not the same as a support commitment, and the README is explicit that the commitment has changed. If your organisation needs a vendor to escalate to, or an SLA on a broken runner, Gauge is the wrong choice and the README says so before you install anything.

The honest reading is that Gauge is a maintained-in-spare-time project with an active release cadence and no support contract. Teams that can live with that get a stable, Apache-2.0 licensed tool. Teams that cannot should stop at the important note.

## Where Gauge gets in the way

The plugin boundary is the main cost. Because step execution happens in a separate runner process communicating over gRPC, a failure can originate in the core, in the runner, or in the handshake between them. Debugging a step that never executes means checking which side dropped it. The repository's plugin/ and runner/ trees exist precisely because that boundary is real, and the go.mod dependency on the Gauge messages package shows the protocol is versioned separately from the core.

Specification quality is the second constraint. Markdown specs are only as good as the step vocabulary behind them, and the closestmatch dependency exists because unmatched steps are a normal occurrence. A team that lets steps proliferate without review ends up with a spec suite that reads well and resolves badly.

Finally, Gauge is not a browser driver. The README points to Taiko, described as headless web browser automation, as a separate project also maintained by Gauge. If your goal is clicking through a web UI, Gauge is the layer that describes the intent and Taiko or another driver is the layer that touches the page. Choosing Gauge does not remove the need to choose a driver.

## Gauge against a single-language BDD framework

The obvious comparison is a BDD framework embedded in one language, such as Cucumber with its Gherkin feature files. Both let you write scenarios in near-natural language and bind them to code. The difference is where the binding runs. Cucumber-style frameworks typically execute steps inside the same process as the test runner, in the same language, so a stack trace points directly at the step definition. Gauge runs steps out of process through a language runner, which is what allows the spec suite and the step code to be in different languages and what makes the plugin architecture possible.

That trade is the whole argument. In-process binding gives simpler debugging and a single dependency graph. Out-of-process binding gives language independence and a cleaner separation between the core tool and the execution layer, at the cost of an extra moving part. If your team writes everything in one language and never intends to change that, the in-process model is less machinery for the same readability benefit. If you have a Java service team and a JavaScript tooling team that both need to contribute steps, Gauge's boundary is the feature, not the overhead.

## Licence, upgrades and what a version bump costs you

Gauge is released under the Apache License, Version 2.0, and the README points to the LICENSE file for the full text. The repository also carries a notice.txt at the top level, which is the conventional place for attribution notices under that licence. Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that notices and the licence text be preserved. That is a description of the licence terms, not legal advice, and any organisation with a formal open source review process should run the LICENSE and notice.txt files through it.

The upgrade cost is structural rather than financial. There is no subscription and no support tier to buy. The cost is the time your team spends when a core release and a runner release drift apart, plus the time spent on any issue that the core team does not reach. The README's own framing, that primary responsibility falls onto individual users and contributors, is the budget line. A team adopting Gauge should assume it owns the runner it depends on, including the possibility of patching it.

## Conclusion

Adopt Gauge if your team already writes acceptance criteria in Markdown and can own a plugin runner in Go, Java or JavaScript, and if you accept that the README asks you to support the tool yourself. Do not adopt it expecting vendor-grade response times, and do not pick it for a one-off UI script where a single-language framework is simpler. Before committing, verify three things: that the runner you need is still published for your language, that the Gauge version in your CI image matches the runner's expected protocol version, and that your team can read the plugin directories listed in the repository root. The README's own wording is the deciding fact: use Gauge only if you are prepared to adopt and support it fully on your own.

## FAQ

### How do I install Gauge?

The README does not list install commands; it directs readers to the Gauge documentation and to a setup guide in the repository wiki. The repository itself is the source for building the tool, with go.mod declaring module github.com/getgauge/gauge and go 1.26.0.

### What language are Gauge specifications written in?

Specifications are authored in Markdown, which is what lets the README describe Gauge as a tool for authoring test cases in the business language. Step implementations live separately and are provided by a language runner.

### Does Gauge run the test steps itself?

No. The core parses specifications and communicates with a language runner over gRPC, using the protocol package listed in go.mod as github.com/getgauge/gauge-proto/go/gauge_messages. Step execution happens on the runner side.

### Is Gauge still actively supported by its original sponsor?

The README states that Gauge's official sponsorship ended in 2021 and that the core team now looks into issues in their spare time, with slower response times and delays on pull requests. It asks readers to use Gauge only if prepared to support it fully on their own.

### What licence is Gauge released under?

Gauge is released under the Apache License, Version 2.0, with the full text in the LICENSE file and an attribution notice in notice.txt at the repository root.

## Sources

- [getgauge/gauge on GitHub](https://github.com/getgauge/gauge)
- [License: Apache-2.0](https://github.com/getgauge/gauge/blob/master/LICENSE)
- [Project website](https://gauge.org)
- [README](https://github.com/getgauge/gauge/blob/master/README.md)
- [Releases](https://github.com/getgauge/gauge/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/getgauge-gauge