diff --git a/cmd/drift.go b/cmd/drift.go index 64a7c7c..32ca160 100644 --- a/cmd/drift.go +++ b/cmd/drift.go @@ -1,12 +1,21 @@ package cmd -import "github.com/spf13/cobra" +import ( + _ "embed" + + "github.com/Use-Tusk/tusk-cli/internal/utils" + "github.com/spf13/cobra" +) const configFlagUsage = "config file (default is .tusk/config.yaml)" +//go:embed short_docs/drift/drift_overview.md +var driftOverviewContent string + var driftCmd = &cobra.Command{ Use: "drift", Short: "Tusk Drift commands", + Long: utils.RenderMarkdown(driftOverviewContent), } func init() { diff --git a/cmd/list.go b/cmd/list.go index 077ece3..4385cac 100644 --- a/cmd/list.go +++ b/cmd/list.go @@ -17,10 +17,10 @@ import ( "github.com/Use-Tusk/tusk-cli/internal/utils" ) -//go:embed short_docs/list.md +//go:embed short_docs/drift/drift_list.md var listContent string -//go:embed short_docs/filter.md +//go:embed short_docs/drift/drift_filter.md var filterContent string var listJSON bool diff --git a/cmd/root.go b/cmd/root.go index 5cdf240..d85cd78 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -30,12 +30,12 @@ var ( ) //go:embed short_docs/overview.md -var overviewContent string +var tuskOverviewContent string var rootCmd = &cobra.Command{ Use: "tusk", Short: "Tusk CLI - Unit test automation and API test record/replay system", - Long: utils.RenderMarkdown(overviewContent), + Long: utils.RenderMarkdown(tuskOverviewContent), Run: func(cmd *cobra.Command, args []string) { showASCIIArt() }, diff --git a/cmd/run.go b/cmd/run.go index 2829498..6c8f35e 100644 --- a/cmd/run.go +++ b/cmd/run.go @@ -57,7 +57,7 @@ var ( validateSuite bool ) -//go:embed short_docs/run.md +//go:embed short_docs/drift/drift_run.md var runContent string var runCmd = &cobra.Command{ diff --git a/cmd/setup.go b/cmd/setup.go index ba0fd36..4168714 100644 --- a/cmd/setup.go +++ b/cmd/setup.go @@ -17,7 +17,7 @@ import ( "golang.org/x/term" ) -//go:embed short_docs/setup.md +//go:embed short_docs/drift/drift_setup.md var setupContent string var ( diff --git a/cmd/short_docs/filter.md b/cmd/short_docs/drift/drift_filter.md similarity index 62% rename from cmd/short_docs/filter.md rename to cmd/short_docs/drift/drift_filter.md index 147be25..9677018 100644 --- a/cmd/short_docs/filter.md +++ b/cmd/short_docs/drift/drift_filter.md @@ -8,9 +8,9 @@ Comma-separated, values are regex. Examples: ```bash -tusk -f 'type=GRAPHQL,op=^GetUser$' -tusk -f 'method=POST,path=/checkout' -tusk -f 'file=2025-09-24.*trace.*\\.jsonl' +tusk drift -f 'type=GRAPHQL,op=^GetUser$' +tusk drift -f 'method=POST,path=/checkout' +tusk drift -f 'file=2025-09-24.*trace.*\\.jsonl' ``` See for more details. diff --git a/cmd/short_docs/list.md b/cmd/short_docs/drift/drift_list.md similarity index 100% rename from cmd/short_docs/list.md rename to cmd/short_docs/drift/drift_list.md diff --git a/cmd/short_docs/drift/drift_overview.md b/cmd/short_docs/drift/drift_overview.md new file mode 100644 index 0000000..ab67803 --- /dev/null +++ b/cmd/short_docs/drift/drift_overview.md @@ -0,0 +1,28 @@ +# Introduction + +Tusk Drift enables you to record and replay traces from real traffic. These recorded traces make up +an API test suite, which you can run locally or in CI/CD pipelines. + +## Concepts overview + +A **trace** represents the full path of an inbound request in your application. + +A **span** represents a unit of work or operation in a trace. We capture all outbound requests made from your service (e.g., database calls, HTTP requests) in the path of a trace. + +Further reading: + +## Setup + +Setup involves creating a `.tusk/config.yaml` file in the directory of the service you wish to test. +This lets Tusk know how to start your service and wait for it to be ready during replay mode. + +You can run `tusk drift setup` to start an AI agent to automatically set up your service for Tusk Drift or `tusk drift init` to start a configuration wizard. + +## Test workflow + +1. Instrument your app with the Tusk SDK. +1. Once your app is up and ready, send traffic to it. + - Tusk will record traces in `.tusk/traces`. + - Shut down your app when you're done. +1. Run `tusk drift run` to run these traces locally. +1. Set up a workflow to run tests in your CI/CD pipeline. diff --git a/cmd/short_docs/run.md b/cmd/short_docs/drift/drift_run.md similarity index 80% rename from cmd/short_docs/run.md rename to cmd/short_docs/drift/drift_run.md index 5c95cbc..78b6233 100644 --- a/cmd/short_docs/run.md +++ b/cmd/short_docs/drift/drift_run.md @@ -42,7 +42,7 @@ An interactive session is started by default; use `-p`/`--print` for noninteract ### Cloud mode -- `tusk run --cloud`: fetches all tests from Tusk Drift Cloud for your service and runs them locally; no Tusk Drift run is created and results are not uploaded. -- `tusk run --cloud --ci`: creates a Tusk Drift run, fetches your test suite from Tusk Drift Cloud, and uploads test results. Use `-a/--all-cloud-trace-tests` to run all tests instead of the run-scoped suite. -- `tusk run --cloud --ci --validate-suite-if-default-branch`: on the default branch, creates a validation run, fetches draft and in-suite tests, and validates they can be replayed before adding them to the suite. On other branches, this flag is ignored and the command behaves like `--cloud --ci`. +- `tusk drift run --cloud`: fetches all tests from Tusk Drift Cloud for your service and runs them locally; no Tusk Drift run is created and results are not uploaded. +- `tusk drift run --cloud --ci`: creates a Tusk Drift run, fetches your test suite from Tusk Drift Cloud, and uploads test results. Use `-a/--all-cloud-trace-tests` to run all tests instead of the run-scoped suite. +- `tusk drift run --cloud --ci --validate-suite-if-default-branch`: on the default branch, creates a validation run, fetches draft and in-suite tests, and validates they can be replayed before adding them to the suite. On other branches, this flag is ignored and the command behaves like `--cloud --ci`. - `--trace-test-id` may be used with `--cloud` to run a single cloud trace test. diff --git a/cmd/short_docs/setup.md b/cmd/short_docs/drift/drift_setup.md similarity index 100% rename from cmd/short_docs/setup.md rename to cmd/short_docs/drift/drift_setup.md diff --git a/cmd/short_docs/overview.md b/cmd/short_docs/overview.md index 8f6dc25..feede5f 100644 --- a/cmd/short_docs/overview.md +++ b/cmd/short_docs/overview.md @@ -1,28 +1,15 @@ -# Introduction +# Tusk CLI -Tusk Drift enables you to record and replay traces from real traffic. These recorded traces make up -an API test suite, which you can run locally or in CI/CD pipelines. +The Tusk CLI provides tools for automated testing workflows across two products: -## Concepts overview +- **Tusk Drift** records real API traffic and replays it as deterministic API tests locally or in CI/CD. +- **Tusk Unit** lets you inspect, review, and apply unit tests generated by Tusk. -A **trace** represents the full path of an inbound request in your application. +## Common starting points -A **span** represents a unit of work or operation in a trace. We capture all outbound requests made from your service (e.g., database calls, HTTP requests) in the path of a trace. +- `tusk drift setup` to configure Tusk Drift for a service +- `tusk drift run` to replay recorded traces +- `tusk unit latest-run` to inspect the latest unit test generation run for your branch +- `tusk auth login` to authenticate with Tusk Cloud -Further reading: - -## Setup - -Setup involves creating a `.tusk/config.yaml` file in the directory of the service you wish to test. -This lets Tusk know how to start your service and wait for it to ready during replay mode. - -You can run `tusk drift setup` to start an AI agent to automatically set up your service for Tusk Drift or `tusk drift init` to start a configuration wizard. - -## Test workflow - -1. Instrument your app with the Tusk SDK. -1. Once your app is up and ready, send traffic to it. - - Tusk will record traces in `.tusk/traces`. - - Shut down your app when you're done. -1. Run `tusk drift run` to run these traces locally. -1. Set up a workflow to run tests in your CI/CD pipeline. +Use `tusk --help` for details on a specific workflow. diff --git a/cmd/short_docs/unit/overview.md b/cmd/short_docs/unit/overview.md new file mode 100644 index 0000000..0e72fd3 --- /dev/null +++ b/cmd/short_docs/unit/overview.md @@ -0,0 +1,16 @@ +# Tusk Unit + +Tusk Unit lets you inspect and apply unit tests generated by Tusk for a pull request or branch. + +The data-returning `tusk unit` subcommands output JSON, which makes them work well in terminals, scripts, and agent workflows. + +## Typical workflow + +1. Check the latest run for the current repo and branch with `tusk unit latest-run`. +2. Inspect the run and its generated scenarios with `tusk unit get-run `. +3. Review a specific scenario with `tusk unit get-scenario --run-id --scenario-id `. +4. Apply generated diffs with `tusk unit get-diffs | jq -r '.files[].diff' | git apply`. + +## Authentication + +Run `tusk auth login`, or set `TUSK_API_KEY` for non-interactive use. diff --git a/cmd/unit.go b/cmd/unit.go index 4c8908c..3e4759f 100644 --- a/cmd/unit.go +++ b/cmd/unit.go @@ -2,18 +2,23 @@ package cmd import ( "context" + _ "embed" "encoding/json" "fmt" "os" "github.com/Use-Tusk/tusk-cli/internal/api" + "github.com/Use-Tusk/tusk-cli/internal/utils" "github.com/spf13/cobra" ) +//go:embed short_docs/unit/overview.md +var unitOverviewContent string + var unitCmd = &cobra.Command{ Use: "unit", Short: "Commands for Tusk unit test workflows", - Long: "Retrieve Tusk unit test generation runs and scenarios for local review and agent workflows.", + Long: utils.RenderMarkdown(unitOverviewContent), SilenceUsage: true, }