Testo command line tool

.github/workflows/qa.yml

@@ -49,7 +49,7 @@ jobs:
       - name: Run unit tests without race detector
         if: runner.os == 'Windows'
         run: |
-          go test -v -cover -coverpkg=./... ./...
+          go test -v -cover -coverpkg=.,./testo...,./internal/... ./...
 
       - name: Test examples output
         run: go test -v -tags e2e -count=1 ./examples_test.go

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+## Added
+
+- Auxiliary command line tool for Testo featuring linter, suites explorer and runner.
+
 ## [1.5.1] - 2026-06-17
 
 ### Fixed

Makefile

@@ -31,15 +31,15 @@ doc:
 
 # get test coverage
 coverage:
-	go test -coverprofile=coverage.out -coverpkg=./... ./...
+	go test -coverprofile=coverage.out -coverpkg=.,./testo...,./internal/... ./...
 	go tool cover -func coverage.out
 
 # visualize test coverage
 coverage-html: coverage
 	go tool cover -html coverage.out
 
 install:
-	go install ./cmd/testo
+	go install ./cmd/...
 
 update-examples-output:
 	./update-examples-output.sh

README.md

@@ -28,6 +28,7 @@ Add some flavor to your tests with
 - Test reflection - deeply inspect test's meta-information.
 - Caching - key-value storage persistent between test runs.
 - [Zero dependencies](./go.mod).
+- [Auxiliary command line tool](./cmd/testo) - linter, suites explorer and runner.
 
 ## Why Testo
 
@@ -112,6 +113,25 @@ Makes it easier to run and debug individual suite tests and adds helpful snippet
 
 ![VSCode extension screenshot showing codelens buttons for running and debugging a test](./vscode-extension/example.png)
 
+## Testo command line tool
+
+Testo has an auxiliary command line tool featuring linter, suites explorer and runner.
+
+[See more here](./cmd/testo).
+
+Example:
+
+```bash
+go install github.com/ozontech/testo/cmd/testo
+
+testo lint ./...
+testo run mypkg/Functional.TestFoo
+testo suites -f "{{ .Package }}/{{ .Suite }}" | fzf
+```
+
+> [!NOTE]
+> This command line tool is _completely optional_ and _is not required_ to run tests.
+
 ## Minimum supported Go version
 
 Testo guarantees to support at least **3 latest major** [Go releases](https://go.dev/doc/devel/release).

cmd/testo/README.md

@@ -0,0 +1,31 @@
+# Testo CTL
+
+Auxiliary command line tool for Testo featuring linter, suites explorer and runner.
+
+> [!WARNING]
+> This tool is experimental, handle with care;
+> may change without warning
+
+## Install
+
+```bash
+go install github.com/ozontech/testo/cmd/testo
+```
+
+## Usage
+
+Run `testo -h` to see available commands:
+
+```txt
+Usage:
+  testo [command]
+
+Available Commands:
+  lint       Run testo linter
+  run        Run testo suites
+  suites     Show testo suites
+  tags       Show project build tags
+  version    Show testo version
+```
+
+Run `testo [command] -h` to show help for the given command.

cmd/testo/internal/cli/cli.go

@@ -0,0 +1,212 @@
+package cli
+
+import (
+	"bytes"
+	"cmp"
+	_ "embed"
+	"errors"
+	"flag"
+	"fmt"
+	"maps"
+	"os"
+	"slices"
+)
+
+//go:embed logo.txt
+var logo string
+
+func usage(f *flag.FlagSet) {
+	var buf bytes.Buffer
+
+	fmt.Fprint(&buf, logo)
+	fmt.Fprintln(&buf, "Usage:")
+	fmt.Fprintf(&buf, "  %s [command]\n\n", os.Args[0])
+	fmt.Fprintln(&buf, "Available Commands:")
+
+	for _, cmd := range slices.Sorted(maps.Keys(commands)) {
+		fmt.Fprintf(&buf, "  %-10s %s\n", cmd, commands[cmd].Short)
+	}
+
+	f.Output().Write(buf.Bytes())
+	f.PrintDefaults()
+}
+
+func Run() {
+	flag.Usage = func() {
+		usage(flag.CommandLine)
+	}
+
+	if len(os.Args) < 2 {
+		flag.Parse()
+		flag.Usage()
+
+		os.Exit(2)
+	}
+
+	if err := run(os.Args[1], os.Args[2:]...); err != nil {
+		var errExit ExitError
+
+		if !errors.As(err, &errExit) {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(2)
+		}
+
+		errExit.Print()
+		os.Exit(errExit.Code)
+	}
+}
+
+func run(command string, args ...string) error {
+	switch command {
+	case "-h", "-help", "--help":
+		usage(flag.CommandLine)
+
+		return nil
+	}
+
+	r, ok := commands[command]
+	if !ok {
+		fmt.Fprintf(flag.CommandLine.Output(), "unknown subcommand: %q\n\n", command)
+
+		usage(flag.CommandLine)
+		os.Exit(2)
+
+		return nil
+	}
+
+	return r.Run(args...)
+}
+
+type Command interface {
+	Run(args ...string) error
+}
+
+var commands = make(map[string]registered)
+
+type registered struct {
+	Short string
+	Run   func(args ...string) error
+}
+
+type config struct {
+	Short string
+	Usage string
+	Long  string
+	Args  ArgsFunc
+}
+
+type Option func(conf *config)
+
+func WithShort(short string) Option {
+	return func(conf *config) {
+		conf.Short = short
+	}
+}
+
+func WithUsage(u string) Option {
+	return func(conf *config) {
+		conf.Usage = u
+	}
+}
+
+func WithLong(u string) Option {
+	return func(conf *config) {
+		conf.Long = u
+	}
+}
+
+func WithoutArgs() Option {
+	return func(conf *config) {
+		conf.Args = func(args ...string) error {
+			if len(args) == 0 {
+				return nil
+			}
+
+			return fmt.Errorf("unexpected argument: %q", args[0])
+		}
+	}
+}
+
+type ArgsFunc func(args ...string) error
+
+func Add[C Command](name string, flags func(f *flag.FlagSet, cmd *C), options ...Option) {
+	var conf config
+
+	for _, o := range options {
+		o(&conf)
+	}
+
+	var command C
+
+	commands[name] = registered{
+		Short: conf.Short,
+		Run: func(args ...string) error {
+			f := flag.NewFlagSet(name, flag.ExitOnError)
+
+			flags(f, &command)
+
+			f.Usage = func() {
+				long := cmp.Or(conf.Long, conf.Short)
+
+				if long != "" {
+					fmt.Fprintf(f.Output(), "%s\n\n", long)
+				}
+
+				fmt.Fprintln(f.Output(), "Usage:")
+
+				var hasFlags bool
+
+				f.VisitAll(func(*flag.Flag) { hasFlags = true })
+
+				if conf.Usage != "" {
+					fmt.Fprintf(f.Output(), "  %s %s %s\n", os.Args[0], name, conf.Usage)
+				} else if hasFlags {
+					fmt.Fprintf(f.Output(), "  %s %s [flags]\n", os.Args[0], name)
+				} else {
+					fmt.Fprintf(f.Output(), "  %s %s\n", os.Args[0], name)
+				}
+
+				if hasFlags {
+					fmt.Fprintln(f.Output(), "\nFlags:")
+
+					f.PrintDefaults()
+				}
+			}
+
+			if err := parseFlagSet(f, args); err != nil {
+				return err
+			}
+
+			positional := f.Args()
+
+			if conf.Args != nil {
+				if err := conf.Args(positional...); err != nil {
+					return fmt.Errorf("%s %s: %w", os.Args[0], name, err)
+				}
+			}
+
+			return command.Run(positional...)
+		},
+	}
+}
+
+func parseFlagSet(f *flag.FlagSet, args []string) error {
+	positional := make([]string, 0, len(args))
+
+	for {
+		if err := f.Parse(args); err != nil {
+			return err
+		}
+
+		args = args[len(args)-f.NArg():]
+		if len(args) == 0 {
+			break
+		}
+
+		positional = append(positional, args[0])
+
+		args = args[1:]
+	}
+
+	return f.Parse(positional)
+}

cmd/testo/internal/cli/errors.go

@@ -0,0 +1,45 @@
+package cli
+
+import (
+	"fmt"
+	"os"
+)
+
+type ExitError struct {
+	Code int
+
+	stdout string
+	stderr string
+}
+
+func (e ExitError) Error() string {
+	return fmt.Sprintf("exit code %d", e.Code)
+}
+
+func Exit(code int) ExitError {
+	return ExitError{
+		Code: code,
+	}
+}
+
+func (e ExitError) Stdout(s string) ExitError {
+	e.stdout = s
+
+	return e
+}
+
+func (e ExitError) Stderr(s string) ExitError {
+	e.stderr = s
+
+	return e
+}
+
+func (e ExitError) Print() {
+	if e.stdout != "" {
+		fmt.Fprint(os.Stdout, e.stdout)
+	}
+
+	if e.stderr != "" {
+		fmt.Fprint(os.Stderr, e.stderr)
+	}
+}