Data structure testing library (assertly)
This library is compatible with Go 1.8+
Please refer to CHANGELOG.md if you encounter breaking changes.
Introduction
This library enables complex data structure testing, specifically:
- Realtime transformation or casting of incompatible data types with directives system.
- Consistent way of testing of unordered structures.
- Contains, Range, RegExp support on any data structure deeph level.
- Switch case directive to provide expected value alternatives based on actual switch/case input match.
- Macro system enabling complex predicate and expression evaluation, and customization.
Motivation
This library has been created as a way to unify original testing approaches introduced to dsunit and endly
Usage
import(
"github.com/stretchr/testify/assert"
"github.com/viant/assertly"
)
func Test_XX(t *testing.T) {
var actualRecords []*User = //get actual
var expectedRecords []*User = //get expected
assertly.AssertValues(t, expectedRecords, actualRecords)
//or with custom path and testing.T integration
validation, err := assertly.Assert(expected, actual, assertly.NewDataPath("/"))
assert.EqualValues(t, 0, validation.FailedCount, validation.Report())
}
Validation
Validation rules:
- JSON textual data is converted into data structure
- New Line Delimited JSON is converted into data structure collection.
- Object/Struct is converted into data structure
- Only existing keys/fields in expected data structure are validated
- Only existing items in the array/slice are validated
- Directive and macros/predicate provide validation extension
- The following expression can be used on any data structure level:
| Validation Type | input | expected expression | example |
|---|---|---|---|
| Equal | actual | expected | a:a |
| Not Equal | actual | !expected | a:!b |
| Contains | actual | /expected/ | abcd:/bc/ |
| Not Contains | actual | !/expected/ | abcd:!/xc/ |
| RegExpr | actual | ~/expected/ | 1234a:/\d+/ |
| Not RegExpr | actual | !~/expected/ | 1234:!/\w/ |
| Between | actual | /[minExpected..maxExpected]/ | 12:/[1..13]/ |
| exists | n/a | { "key": "@exists@" } | |
| not exists | n/a | { "key": "@!exists@" } |
example:
func Test_XX(t *testing.T) {
var expected = `
{
"Meta": "abc",
"Table": "/table_/",
"Rows": [
{
"id": 1,
"name": "~/name (\\d+)/",
"@exists@":"dob"
},
{
"id": 2,
"name": "name 2",
"settings": {
"k1": "v2"
}
},
{
"id": 2,
"name": "name 2"
}
]
}`,
var actual = `
{
"Table": "table_xx",
"Rows": [
{
"id": 1,
"name": "name 12",
"dob":"2018-01-01"
},
{
"id": 2,
"name": "name 2",
"settings": {
"k1": "v20"
}
},
{
"id": 4,
"name": "name 2"
}
]
}`,
validation, err := assertly.Assert(expected, actual, assertly.NewDataPath("/"))
assert.EqualValues(t, 0, validation.FailedCount, validation.Report())
}
Directive
Directive is an instruction provide validator with transformation or validation rules.
KeyExistsDirective = "@exists@"
KeyDoesNotExistsDirective = "@!exists@"
TimeFormatDirective = "@timeFormat@"
SwitchByDirective = "@switchCaseBy@"
CastDataTypeDirective = "@cast@"
IndexByDirective = "@indexBy@"
CaseSensitiveDirective = @caseSensitive@
SourceDirective = "@source@"
SourceTextDirective = "@sortText@"
Index by
@indexBy@ - index by directive indexes a slice for validation process, specifically.
- Two unordered array/slice/collection that can be index by a unique fields
- A map with a actual array/slice/collection that can be ordered by unique fields
Example 1
#expected
{
"@indexBy@":"id",
"1" :{"id":1, "name":"name1"},
"2" :{"id":2, "name":"name2"}
}
#actual
[
{"id":1, "name":"name1"},
{"id":2, "name":"name2"}
]
Example 2
#expected
{"@indexBy@":"id"}
{"id":1, "name":"name1"}
{"id":2, "name":"name2"}#actual
{"id":1, "name":"name1"}
{"id":2, "name":"name2"}Example 3
#expected
{"@indexBy@":"request.id"}
{"request:"{"id":1111, "name":"name1"}, "ts":189321233}
{"request:"{"id":2222, "name":"name2"}, "ts":189321235}#actual
{"request:"{"id":2222, "name":"name2"}, "ts":189321235}
{"request:"{"id":1111, "name":"name1"}, "ts":189321233}Switch/case
@switchCaseBy@ - switch directive instructs a validator to select matching expected subset based on some actual value. . For non deterministic system there could be various alternative output for the same input.
Example 1
#expected
[
{
"@switchCaseBy@":["experimentID"]
},
{
"1":{"experimentID":1, "seq":1, "outcome":[1.53,7.42,6.34]},
"2":{"experimentID":2, "seq":1, "outcome":[3.53,6.32,3.34]}
},
{
"1":{"experimentID":1, "seq":2, "outcome":[5.63,4.3]},
"2":{"experimentID":1, "seq":2, "outcome":[3.65,3.2]}
}
]#actual
{"experimentID":1, "seq":1, "outcome":[1.53,7.42,6.34]}
{"experimentID":1, "seq":2, "outcome":[5.63,4.3]}Example 2
#expected
[
{
"@switchCaseBy@":["experimentID"]
},
{
"1":{"experimentID":1, "seq":1, "outcome":[1.53,7.42,6.34]},
"2":{"experimentID":2, "seq":1, "outcome":[3.53,6.32,3.34]},
"shared": {"k1":"v1", "k2":"v2"}
},
{
"1":{"experimentID":1, "seq":2, "outcome":[5.63,4.3]},
"2":{"experimentID":1, "seq":2, "outcome":[3.65,3.2]},
"shared": {"k1":"v10", "k2":"v20"}
}
]#actual
{"experimentID":1, "seq":1, "outcome":[1.53,7.42,6.34], "k1":"v1", "k2":"v2"}
{"experimentID":1, "seq":2, "outcome":[5.63,4.3], "k1":"v10", "k2":"v20"}Time format
@timeFormat@ - time format directive instructs a validator to convert data into time with specified time format before actual validation takes place.
Time format is expressed in java style date format.
Example
#expected
expected := map[string]interface{}{
"@timeFormat@date": "yyyy-MM-dd",
"@timeFormat@ts": "yyyy-MM-dd hh:mm:ss"
"@timeFormat@" "yyyy-MM-dd hh:mm:ss" //default time format
"id":123,
"date": "2019-01-01",
"ts": "2019-01-01 12:00:01",
}#actual
expected := map[string]interface{}{
"id":123,
"date": "2019-01-01 12:00:01",,
"ts": "2019-01-01 12:00:01",
}Time layout
@timeLayout@ - time format directive instructs a validator to convert data into time with specified time format before actual validation takes place.
Time layout uses golang time layout.
Example
#expected
expected := map[string]interface{}{
"@timeFormat@date": "yyyy-MM-dd",
"@timeFormat@ts": "yyyy-MM-dd hh:mm:ss"
"@timeFormat@" "yyyy-MM-dd hh:mm:ss" //default time format
"id":123,
"date": "2019-01-01",
"ts": "2019-01-01 12:00:01",
}#actual
expected := map[string]interface{}{
"id":123,
"date": "2019-01-01 12:00:01",,
"ts": "2019-01-01 12:00:01",
}Cast data type
@cast@ - instruct a validator to convert data to the specified data type before actual validation takes place.
Supported data type casting:
- int
- float
- boolean
Example
#expected
[
{
"@case@field1":"float","@case@field2":"int"
},
{
"field1":2.3,
"field2":123
},
{
"field1":6.3,
"field2":551
}
]#actual
{"field1":"2.3","field2":"123"}
{"field1":"6.3","field2":"551"}CaseSensitiveDirective
By default map key match is case sensitive, directive allows to disable that behaviours.
Source directive
Source directive is helper directive providing additional information about data point source, i.e. file.json#L113
Macro and predicates
The macro is an expression with parameters that expands original text value. The general format of macro: <ds:MACRO_NAME [json formated array of parameters]>
The following macro are build-in:
| Name | Parameters | Description | Example |
|---|---|---|---|
| env | name env variable | Returns value env variable | <ds:env["user"]> |
| nil | n/a | Returns nil value | <ds:nil> |
| cast | type name | Returns value env variable | <ds:cast["int", "123"]> |
| current_timestamp | n/a | Returns time.Now() | <ds:current_timestamp> |
| dob | user age, month, day, format(yyyy-MM-dd as default) | Returns Date Of Birth | <ds:dob> |
Predicates
Predicate allows expected value to be evaluated with actual dataset value using custom predicate logic.
| Name | Parameters | Description | Example |
|---|---|---|---|
| between | from, to values | Evaluate actual value with between predicate | <ds:between[1.888889, 1.88889]> |
| within_sec | base time, delta, optional date format | Evaluate if actual time is within delta of the base time | <ds:within_sec["now", 6, "yyyyMMdd HH:mm:ss"]> |
Example
expected := `<ds:between[1,10]>`
actual := 3 expected := `1<ds:env["USER"]>3`,
actual := fmt.Sprintf("1%v3", os.Getenv("USER")) expected := `<ds:dob[3, 6, 3>`
actual := 2015-06-03 expected := `<ds:dob[3, 6, 3,"yyyy-MM-dd"]>`
actual := 2015-06-03 expected := `<ds:dob[3, 6, 3,"yyyy"]>`
actual := 2015 expected := `<ds:dob[3, 9, 2,"yyyy-MM"]>`
actual := 2015-09 expected := `<ds:dob[5, 12, 25,"-MM-dd"]>`
actual := 12-25GoCover
License
The source code is made available under the terms of the Apache License, Version 2, as stated in the file LICENSE.
Individual files may be made available under their own specific license, all compatible with Apache License, Version 2. Please see individual files for details.
Credits and Acknowledgements
Library Author: Adrian Witas