golium

README

Golium

This library aims to speed up the generation of acceptance tests with Cucumber and Behaviour-Driven Development (BDD). It is based on godog which is the official Cucumber BDD framework for Golang.

This library leverages godog with 2 main additions:

• Introduce a context in the step functions. The context is based on the standard Golang context: context.Context. It enables to share information among steps without using global variables.
• Provide common steps for some protocols. The current version provides steps for HTTP and DNS protocols.

This is a very initial version which may suffer big changes in the short-term.

Configuration

The library has a default configuration. However, these settings can be changed with environment variables.

Environment Variable	Default	Description
SUITE	golium	Suite name (for logging purposes)
ENVIRONMENT	local	Name of the environment. Golium reads the environment configuration from the file ${DIR_ENVIRONMENTS}/${ENVIRONMENT}.yml. This configuration is mandatory. An optional configuration file to separate sensitive data can be placed at ${DIR_ENVIRONMENTS}/${ENVIRONMENT}-private.yml. Configuration is available to steps with the function GetEnvironment().
DIR_SCHEMAS	./schemas	Directory where the JSON schemas are available. These JSON schemas are used by some steps to validate some output (e.g. the body of the HTTP response).
DIR_ENVIRONMENTS	./environments	Directory where the configuration for each environment is available. Each environment must have a yml file in this directory.
LOG_DIRECTORY	./logs	Directory where logs are written. There may be multiple log files. Currently, there is one for tracing the execution of the steps and scenarios (golium.log) and another one to save the HTTP requests and HTTP responses (http.log).
LOG_LEVEL	INFO	Log level. Possible values are defined by logrus library.
LOG_ENCODE	false	Encode sensible values when configured. Each encoder has its pre-defined sensible values

Example

The library includes a complete example with some scenarios for HTTP and DNS protocols in the directory test/acceptance.

Environment

Using docker-compose to build test environment with all dependent services for each example: redis, rabbit, elasticsearch and minio:

docker-compose build

Tests

Run acceptance tests:

docker-compose run --rm golium sh -c "make test-acceptance"

Run tests filtering by tag:

docker-compose run --rm golium sh -c "make test-run-tag TAG=@rabbit"

The examples contains the following directories:

• features. Features for the test suite in BDD.
• environments. It contains the configuration for each environment in a specific yml file. This directory is configured with the environment variable: DIR_ENVIRONMENTS.
• schemas. JSON schemas. This is used by some steps to validate an input (e.g. the HTTP response body). This directory is configured with the environment variable: DIR_SCHEMAS.
• logs. It stores the log files generated by the execution of the suite tests.

License

Copyright 2021 Telefonica Cybersecurity & Cloud Tech SL

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or lied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Index

• Constants
• Variables
• func ColumnsChecker(cells []*messages.PickleTableCell, n int) error
• func ContainsString(expected string, values []string) bool
• func ConvertTableColumnToArray(ctx context.Context, t *godog.Table) ([]string, error)
• func ConvertTableToMap(ctx context.Context, t *godog.Table) (map[string]interface{}, error)
• func ConvertTableToMultiMap(ctx context.Context, t *godog.Table) (map[string][]string, error)
• func ConvertTableWithHeaderToStructSlice(ctx context.Context, t *godog.Table, slicePtr interface{}) error
• func ConvertTableWithoutHeaderToStruct(ctx context.Context, t *godog.Table, v interface{}) error
• func GetConfig() *cfg.Config
• func InitializeContext(ctx context.Context) context.Context
• func NewTable(src [][]string) *godog.Table
• func RemoveHeaders(t *godog.Table) error
• func Value(ctx context.Context, s string) interface{}
• func ValueAsInt(ctx context.Context, s string) (int, error)
• func ValueAsString(ctx context.Context, s string) string
• type ComposedTag
  • func (t ComposedTag) Value(ctx context.Context) interface{}
• type ConfigurePattern
• type Context
  • func GetContext(ctx context.Context) *Context
  • func (c *Context) Get(key string) interface{}
  • func (c *Context) Put(key string, value interface{})
• type ContextKey
• type FieldConversor
  • func NewBoolConverter() *FieldConversor
  • func NewComplex64Converter() *FieldConversor
  • func NewFloat64Converter() *FieldConversor
  • func NewInt64Converter() *FieldConversor
  • func NewSliceConverter() *FieldConversor
  • func NewStringConverter() *FieldConversor
  • func NewUInt64Converter() *FieldConversor
• type KindFormatter
• type Launcher
  • func NewLauncher() *Launcher
  • func NewLauncherWithYaml(path string) *Launcher
  • func (l *Launcher) Launch(testSuiteInitializer func(context.Context, *godog.TestSuiteContext), ...)
• type Logger
  • func GetLogger() *Logger
  • func LoggerFactory(name string) *Logger
  • func (l Logger) Obfuscate(plain string) string
• type Map
  • func GetEnvironment() Map
  • func NewMapFromJSONBytes(buf []byte) Map
• type NamedTag
  • func (t NamedTag) Value(ctx context.Context) interface{}
• type StepsInitializer
• type StringTag
  • func (s StringTag) Value(ctx context.Context) interface{}
• type Tag
  • func NewComposedTag(s string) Tag
  • func NewNamedTag(s string) Tag
  • func NewStringTag(s string) Tag

Constants

const (
	SUFFIX = ".log"
)

Variables

var StrategyFormat = map[reflect.Kind]*FieldConversor{
	reflect.Slice:      NewSliceConverter(),
	reflect.String:     NewStringConverter(),
	reflect.Bool:       NewBoolConverter(),
	reflect.Int:        NewInt64Converter(),
	reflect.Int8:       NewInt64Converter(),
	reflect.Int16:      NewInt64Converter(),
	reflect.Int32:      NewInt64Converter(),
	reflect.Int64:      NewInt64Converter(),
	reflect.Uint:       NewUInt64Converter(),
	reflect.Uint8:      NewUInt64Converter(),
	reflect.Uint16:     NewUInt64Converter(),
	reflect.Uint32:     NewUInt64Converter(),
	reflect.Uint64:     NewUInt64Converter(),
	reflect.Float32:    NewFloat64Converter(),
	reflect.Float64:    NewFloat64Converter(),
	reflect.Complex64:  NewComplex64Converter(),
	reflect.Complex128: NewComplex64Converter(),
}

Functions

func ColumnsChecker

func ColumnsChecker(cells []*messages.PickleTableCell, n int) error

func ContainsString

func ContainsString(expected string, values []string) bool

ContainsString check if a expected value is included in a slice of values.

func ConvertTableColumnToArray

func ConvertTableColumnToArray(ctx context.Context, t *godog.Table) ([]string, error)

ConvertTableColumnToArray converts a godog table with 1 column into a []string.

func ConvertTableToMap

func ConvertTableToMap(ctx context.Context, t *godog.Table) (map[string]interface{}, error)

ConvertTableToMap converts a godog table with 2 columns into a map[string]interface{}.

func ConvertTableToMultiMap

func ConvertTableToMultiMap(ctx context.Context, t *godog.Table) (map[string][]string, error)

ConvertTableToMultiMap converts a godog table with 2 columns into a map[string][]string. The multimap is using url.Values. The multimap is useful to support multiple values for the same key (e.g. for query parameters or HTTP headers).

func ConvertTableWithHeaderToStructSlice

func ConvertTableWithHeaderToStructSlice(ctx context.Context,
	t *godog.Table,
	slicePtr interface{},
) error

func ConvertTableWithoutHeaderToStruct

func ConvertTableWithoutHeaderToStruct(ctx context.Context, t *godog.Table, v interface{}) error

func GetConfig

func GetConfig() *cfg.Config

GetConfig returns the golium configuration. This configuration includes relevant information as the environment or the directories for some assets or log files.

func InitializeContext

func InitializeContext(ctx context.Context) context.Context

InitializeContext adds the Context to the context. The new context is returned because context is immutable.

func NewTable

func NewTable(src [][]string) *godog.Table

NewTable Aux function that creates a new table from string matrix for testing purposes.

func RemoveHeaders

func RemoveHeaders(t *godog.Table) error

Remove headers form table

func Value

func Value(ctx context.Context, s string) interface{}

Value converts a value as a string to consider some golium patterns. Supported patterns:

• Booleans: [TRUE] or [FALSE]
• Null value: [NULL]
• Empty value: [EMPTY]
• Number: [NUMBER:1234] or [NUMBER:1234.67]
• Configuration parameters: [CONF:test.parameter]
• Context values: [CTXT:test.context]
• SHA256: [SHA256:text.to.be.hashed]
• BASE64: [BASE64:text.to.be.base64.encoded]
• Time: [NOW:+24h:unix] with the format: [NOW:{duration}:{format}] The value {duration} can be empty (there is no change from now timestamp) or a format valid for time.ParseDuration function. Currently, it supports the following units: "ns", "us", "ms", "s", "m", "h". The format can be "unix" or a layout valid for time.Format function. It is possible to use [NOW]. In that case, it returns an int64 with the now timestamp in unix format.

Most cases, the return value is a string except for the following cases: - [TRUE] and [FALSE] return a bool type. - [NUMBER:1234] returns a float64 if s only contains this tag and there is no surrounding text. - [NOW:{duration}:{format}] returns an int64 when {format} is "unix".

func ValueAsInt

func ValueAsInt(ctx context.Context, s string) (int, error)

ValueAsInt invokes Value and converts the return value to int.

func ValueAsString

func ValueAsString(ctx context.Context, s string) string

ValueAsString invokes Value and converts the return value to string.

Types

type ComposedTag

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

ComposedTag is a composition of tags, including StringTags, NamedTags and other ComposedTags to provide an evaluation.

func (ComposedTag) Value

func (t ComposedTag) Value(ctx context.Context) interface{}

type ConfigurePattern

type ConfigurePattern func(destination reflect.Value, fieldValueStr string, value interface{}) error

ConfigurePattern func to apply transformation into destination

type Context

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

Context contains the context required for common utilities. It contains a map[string]interface{} to store global values and find them with [CTXT:xxx] tag.

func GetContext

func GetContext(ctx context.Context) *Context

GetContext returns the Context stored in context. Note that the context should be previously initialized with InitializeContext function.

func (*Context) Get

func (c *Context) Get(key string) interface{}

Get returns an element from Context.Ctx. If the value does not exist, it returns nil.

func (*Context) Put

func (c *Context) Put(key string, value interface{})

Put writes an element in the context.

type ContextKey

type ContextKey string

ContextKey defines a type to store the Context in context.Context.

type FieldConversor

type FieldConversor struct {
	Pattern ConfigurePattern
}

FieldConversor

func NewBoolConverter

func NewBoolConverter() *FieldConversor

NewBoolConverter Constructor

func NewComplex64Converter

func NewComplex64Converter() *FieldConversor

NewComplex64Converter Constructor

func NewFloat64Converter

func NewFloat64Converter() *FieldConversor

NewFloat64Converter Constructor

func NewInt64Converter

func NewInt64Converter() *FieldConversor

NewInt64Converter Constructor

func NewSliceConverter

func NewSliceConverter() *FieldConversor

NewSliceConverter Constructor

func NewStringConverter

func NewStringConverter() *FieldConversor

NewStringConverter Constructor

func NewUInt64Converter

func NewUInt64Converter() *FieldConversor

NewUInt64Converter Constructor

type KindFormatter

type KindFormatter interface {
	// contains filtered or unexported methods
}

KindFormatter with format to apply conversion

type Launcher

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

Launcher is responsible to launch golium (based on godog). The default configuration is merged with environment variables.

func NewLauncher

func NewLauncher() *Launcher

NewLauncher with a default configuration.

func NewLauncherWithYaml

func NewLauncherWithYaml(path string) *Launcher

NewLauncherWithYaml with a configuration from a yaml file. The yaml file is merged with environment variables.

func (*Launcher) Launch

func (l *Launcher) Launch(testSuiteInitializer func(context.Context, *godog.TestSuiteContext),
	scenarioInitializer func(context.Context, *godog.ScenarioContext))

Launch golium.

type Logger

type Logger struct {
	*logrus.Logger
	Encode bool
}

Logger logs in a configurable file.

func GetLogger

func GetLogger() *Logger

GetLogger returns the logger for DNS requests and responses. If the logger is not created yet, it creates a new instance of Logger.

func LoggerFactory

func LoggerFactory(name string) *Logger

LoggerFactory returns a Logger instance.

func (Logger) Obfuscate

func (l Logger) Obfuscate(plain string) string

type Map

type Map interface {
	Get(path string) interface{}
}

Map is an interface to get elements from a data structure with a dot notation.

func GetEnvironment

func GetEnvironment() Map

GetEnvironment returns the environment configuration.

func NewMapFromJSONBytes

func NewMapFromJSONBytes(buf []byte) Map

NewMapFromJSONBytes creates a Map from a slice of bytes of a JSON document.

type NamedTag

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

NamedTag is a Tag that can be evaluated with a tag function depending on the name of the tag.

func (NamedTag) Value

func (t NamedTag) Value(ctx context.Context) interface{}

type StepsInitializer

type StepsInitializer interface {
	// InitializeSteps initializes a set of steps (e.g. http steps) to make them available
	// but using a context.
	InitializeSteps(ctx context.Context, scenCtx *godog.ScenarioContext) context.Context
}

StepsInitializer is an interface to initialize the steps in godog, but extending godog initializer with a context.

type StringTag

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

StringTag represents a implicit tag composed of a text. This tag is used to compose a string with a tag to generate a new string.

func (StringTag) Value

func (s StringTag) Value(ctx context.Context) interface{}

type Tag

type Tag interface {
	Value(ctx context.Context) interface{}
}

Tag interface to calculate the value of a tag. A golium tag is a text surrounded by brackets that can be evaluated into a value. For example: [CONF:property]

func NewComposedTag

func NewComposedTag(s string) Tag

NewComposedTag creates a ComposedTag.

func NewNamedTag

func NewNamedTag(s string) Tag

NewNamedTag creates a NamedTag.

func NewStringTag

func NewStringTag(s string) Tag

NewStringTag creates a Tag that evaluated to the string without any modification.