scenarigo

README

Scenarigo

A scenario-based API testing tool for HTTP/gRPC server.

Overview

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}}"

Installation

go install command

$ go install github.com/zoncoen/scenarigo/cmd/scenarigo@v0.9.0

from release page

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.

Setup

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.
# plugins:                  # Specify configurations to build plugins.
#   plugin.so:              # Map keys specify plugin output file path from the root directory of plugins.
#     src: ./path/to/plugin # Specify the source file, directory, or "go gettable" module path of the plugin.
#     setup: '{{Setup}}'    # Specify the setup function by the template string. This function will be called before running tests only once.

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.

Usage

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 scenario files
  plugin      provide operations for plugins
  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.

How to write test scenarios

You can write test scenarios easily in YAML.

Send HTTP requests

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

Check HTTP responses

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

Template string

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]}}'

Documentation

Overview

Package scenarigo provides end-to-end scenario testing framework for APIs. It loads YAML files as scenarios and executes them.

Index

• Variables
• func RunScenario(ctx *context.Context, s *schema.Scenario) *context.Context
• func WithConfig(config *schema.Config) func(*Runner) error
• func WithOptionsFromEnv(isEnv bool) func(*Runner) error
• func WithPluginDir(path string) func(*Runner) error
• func WithScenarios(paths ...string) func(*Runner) error
• func WithScenariosFromReader(readers ...io.Reader) func(*Runner) error
• type Runner
  • func NewRunner(opts ...func(*Runner) error) (*Runner, error)
  • func (r *Runner) Run(ctx *context.Context)
  • func (r *Runner) ScenarioFiles() []string

Variables

var GoModBytes []byte

Functions

func RunScenario

func RunScenario(ctx *context.Context, s *schema.Scenario) *context.Context

RunScenario runs a test scenario s.

func WithConfig

func WithConfig(config *schema.Config) func(*Runner) error

WithConfig returns a option which sets configuration.

func WithOptionsFromEnv

func WithOptionsFromEnv(isEnv bool) func(*Runner) error

WithOptionsFromEnv returns a option which sets flag whether accepts configuration from ENV. Currently Available ENV variables are the following. - SCENARIGO_COLOR=(1|true|TRUE) nolint:stylecheck

func WithPluginDir

func WithPluginDir(path string) func(*Runner) error

WithPluginDir returns a option which sets plugin root directory.

func WithScenarios

func WithScenarios(paths ...string) func(*Runner) error

WithScenarios returns a option which finds and sets test scenario files.

func WithScenariosFromReader

func WithScenariosFromReader(readers ...io.Reader) func(*Runner) error

WithScenariosFromReader returns a option which sets readers to read scenario contents.

Types

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner represents a test runner.

func NewRunner

func NewRunner(opts ...func(*Runner) error) (*Runner, error)

NewRunner returns a new test runner.

func (*Runner) Run

func (r *Runner) Run(ctx *context.Context)

Run runs all tests.

func (*Runner) ScenarioFiles

func (r *Runner) ScenarioFiles() []string

ScenarioFiles returns all scenario file paths.