A scenario-based API testing tool for HTTP/gRPC server.
Scenarigo is a scenario-based API testing tool for HTTP/gRPC server. It is written in Go, enable to customize by the plugin package of Go. You can write test scenarios as YAML files and executes them.
title: get scenarigo repository
steps:
- title: GET https://api.github.com/repos/zoncoen/scenarigo
vars:
user: zoncoen
repo: scenarigo
protocol: http
request:
method: GET
url: "https://api.github.com/repos/{{vars.user}}/{{vars.repo}}"
expect:
code: OK
body:
name: "{{vars.repo}}"
$ go install github.com/zoncoen/scenarigo/cmd/scenarigo@v0.8.1
Go to the releases page and download the zip file. Unpack the zip file, and put the binary to a directory in your $PATH
.
You can download the latest command into the ./scenarigo
directory with the following one-liner code. Place the binary ./scenarigo/scenarigo
into your $PATH
.
$ version=$(curl -s https://api.github.com/repos/zoncoen/scenarigo/releases/latest | jq -r '.tag_name') && \
go_version='go1.17' && \
curl -sLJ https://github.com/zoncoen/scenarigo/releases/download/${version}/scenarigo_${version}_${go_version}_$(uname)_$(uname -m).tar.gz -o scenarigo.tar.gz && \
mkdir ./scenarigo && tar -zxvf ./scenarigo.tar.gz -C ./scenarigo && rm scenarigo.tar.gz
Notes: If you use the plugin mechanism, the scenarigo
command and plugins must be built using the same version of Go.
You can generate a configuration file scenarigo.yaml
via the following command.
$ scenarigo config init
schemaVersion: config/v1
scenarios: [] # Specify test scenario files and directories.
pluginDirectory: ./ # Specify the root directory of plugins.
output:
verbose: false # Enable verbose output.
# colored: false # Enable colored output with ANSI color escape codes. It is enabled by default but disabled when a NO_COLOR environment variable is set (regardless of its value).
# report:
# json:
# filename: ./report.json # Specify a filename for test report output in JSON.
# junit:
# filename: ./junit.xml # Specify a filename for test report output in JUnit XML format.
scenarigo run
executes test scenarios based on the configuration file.
schemaVersion: config/v1
scenarios:
- github.yaml
title: get scenarigo repository
steps:
- title: GET https://api.github.com/repos/zoncoen/scenarigo
vars:
user: zoncoen
repo: scenarigo
protocol: http
request:
method: GET
url: "https://api.github.com/repos/{{vars.user}}/{{vars.repo}}"
expect:
code: OK
body:
name: "{{vars.repo}}"
$ scenarigo run
ok github.yaml 0.068s
You can see all commands and options by scenarigo help
.
scenarigo is a scenario-based API testing tool.
Usage:
scenarigo [command]
Available Commands:
config manage the scenarigo configuration file
help Help about any command
list list the test scenarios
run run test scenarios
version print scenarigo version
Flags:
-c, --config string specify configuration file path
-h, --help help for scenarigo
Use "scenarigo [command] --help" for more information about a command.
You can write test scenarios easily in YAML.
A test scenario consists of some steps. A step represents an API request. The scenario steps will be run from top to bottom sequentially.
This simple example has a step that sends a GET
request to http://example.com/message
.
title: check /message
steps:
- title: GET /message
protocol: http
request:
method: GET
url: http://example.com/message
To send a query parameter, add it directly to the URL or use the query
field.
title: check /message
steps:
- title: GET /message
protocol: http
request:
method: GET
url: http://example.com/message
query:
id: 1
You can use other methods to send data to your APIs.
title: check /message
steps:
- title: POST /message
protocol: http
request:
method: POST
url: http://example.com/message
body:
message: hello
By default, Scenarigo will send body data as JSON. If you want to use other formats, set the Content-Type
header.
title: check /message
steps:
- title: POST /message
protocol: http
request:
method: POST
url: http://example.com/message
header:
Content-Type: application/x-www-form-urlencoded
body:
message: hello
Available Content-Type
header to encode request body is the following.
application/json
(default)text/plain
application/x-www-form-urlencoded
You can test your APIs by checking responses. If the result differs expected values, Scenarigo aborts the execution of the test scenario and notify the error.
title: check /message
steps:
- title: GET /message
protocol: http
request:
method: GET
url: http://example.com/message
query:
id: 1
expect:
code: OK
header:
Content-Type: application/json; charset=utf-8
body:
id: 1
message: hello
Scenarigo provides the original template string feature. It enables to store and reuse values in test scenarios.
The vars
field defines variables that can be referred by template string like '{{vars.id}}'
.
title: check /message
vars:
id: 1
steps:
- title: GET /message
protocol: http
request:
method: GET
url: http://example.com/message
query:
id: '{{vars.id}}'
You can define "step" scope variables that can't be accessed from other steps.
title: check /message
steps:
- title: GET /message
vars:
- 1
protocol: http
request:
method: GET
url: http://example.com/message
query:
id: '{{vars[0]}}'