README
¶
Gomatch
Library created for testing JSON against patterns. The goal was to be able to validate JSON focusing only on parts essential in given test case so tests are more expressive and less fragile. It can be used with both unit tests and functional tests.
When used with Gherkin driven BDD tests it makes scenarios more compact and readable. See Gherkin example
Contests
Installation
go get github.com/jfilipczyk/gomatch
Basic usage
actual := `
{
"id": 351,
"name": "John Smith",
"address": {
"city": "Boston"
}
}
`
expected := `
{
"id": "@number@",
"name": "John Smith",
"address": {
"city": "@string@"
}
}
`
m := gomatch.NewDefaultJSONMatcher()
ok, err := m.Match(expected, actual)
if ok {
fmt.Printf("actual JSON matches expected JSON")
} else {
fmt.Printf("actual JSON does not match expected JSON: %s", err.Error())
}
Available patterns
@string@@number@@bool@@array@@uuid@@email@@wildcard@@...@- unbounded array or object
Unbounded pattern
It can be used at the end of an array to allow any extra array elements:
[
"John Smith",
"Joe Doe",
"@...@"
]
It can be used at the end of an object to allow any extra keys:
{
"id": 351,
"name": "John Smith",
"@...@": ""
}
Gherkin example
Gomatch was created to use it together with tools like GODOG. The goal was to be able to validate JSON response focusing only on parts essential in given scenario.
Feature: User management API
In order to provide GUI for user management
As a frontent developer
I need to be able to create, retrive, update and delete users
Scenario: Get list of users sorted by username ascending
Given the database contains users:
| Username | Email |
| john.smith | john.smith@example.com |
| alvin34 | alvin34@example.com |
| mike1990 | mike.jones@example.com |
When I send "GET" request to "/v1/users?sortBy=username&sortDir=asc"
Then the response code should be 200
And the response body should match json:
"""
{
"items": [
{
"username": "alvin34",
"@...@": ""
},
{
"username": "john.smith",
"@...@": ""
},
{
"username": "mike1990",
"@...@": ""
}
],
"@...@": ""
}
"""
License
This library is distributed under the MIT license. Please see the LICENSE file.
Credits
This library was inspired by PHP Matcher
Logo
The Go gopher was designed by Renee French. (http://reneefrench.blogspot.com/). Gomatch logo was based on a gopher created by Takuya Ueda (https://twitter.com/tenntenn). Licensed under the Creative Commons 3.0 Attributions license. Gopher eyes were changed.
Documentation
¶
Overview ¶
Package gomatch provides types for pattern based JSON matching.
It provides JSONMatcher type which performs deep comparison of two JSON strings. JSONMatcher may be created with a set of ValueMatcher implementations. A ValueMatcher is used to make comparison less strict than a regular value comparison.
Use NewDefaultJSONMatcher to create JSONMatcher with a chain of all available ValueMatcher implementations.
Basic usage:
actual := `
{
"id": 351,
"name": "John Smith",
"address": {
"city": "Boston"
}
}
`
expected := `
{
"id": "@number@",
"name": "John Smith",
"address": {
"city": "@string@"
}
}
`
m := gomatch.NewDefaultJSONMatcher()
ok, err := m.Match(expected, actual)
if ok {
fmt.Printf("actual JSON matches expected JSON")
} else {
fmt.Printf("actual JSON does not match expected JSON: %s", err.Error())
}
Use NewJSONMatcher to create JSONMatcher with a custom ValueMatcher implementation. Use ChainMatcher to chain multiple ValueMacher implementations.
m := gomatch.NewJSONMatcher(
NewChainMatcher(
[]ValueMatcher{
NewStringMatcher("@string@"),
NewNumberMatcher("@number@"),
},
)
);
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ArrayMatcher ¶
type ArrayMatcher struct {
// contains filtered or unexported fields
}
An ArrayMatcher matches []interface{}.
func NewArrayMatcher ¶
func NewArrayMatcher(pattern string) *ArrayMatcher
NewArrayMatcher creates ArrayMatcher.
func (*ArrayMatcher) CanMatch ¶
func (m *ArrayMatcher) CanMatch(p interface{}) bool
CanMatch returns true if pattern p can be handled
func (*ArrayMatcher) Match ¶
func (m *ArrayMatcher) Match(p, v interface{}) (bool, error)
Match performs value matching against given pattern.
type BoolMatcher ¶
type BoolMatcher struct {
// contains filtered or unexported fields
}
A BoolMatcher matches booleans.
func NewBoolMatcher ¶
func NewBoolMatcher(pattern string) *BoolMatcher
NewBoolMatcher creates BoolMatcher.
func (*BoolMatcher) CanMatch ¶
func (m *BoolMatcher) CanMatch(p interface{}) bool
CanMatch returns true if pattern p can be handled
func (*BoolMatcher) Match ¶
func (m *BoolMatcher) Match(p, v interface{}) (bool, error)
Match performs value matching against given pattern.
type ChainMatcher ¶
type ChainMatcher struct {
// contains filtered or unexported fields
}
A ChainMatcher allows to chain multiple value matchers
func NewChainMatcher ¶
func NewChainMatcher(matchers []ValueMatcher) *ChainMatcher
NewChainMatcher creates ChainMatcher.
func (*ChainMatcher) CanMatch ¶
func (m *ChainMatcher) CanMatch(p interface{}) bool
CanMatch returns true if pattern p can be handled by any of internal matchers
func (*ChainMatcher) Match ¶
func (m *ChainMatcher) Match(p, v interface{}) (bool, error)
Match performs value matching against given pattern. It iterates through internal matchers and uses first which can handle given pattern.
type EmailMatcher ¶ added in v1.1.0
type EmailMatcher struct {
// contains filtered or unexported fields
}
An EmailMatcher matches email
func NewEmailMatcher ¶ added in v1.1.0
func NewEmailMatcher(pattern string) *EmailMatcher
NewEmailMatcher creates EmailMatcher.
func (*EmailMatcher) CanMatch ¶ added in v1.1.0
func (m *EmailMatcher) CanMatch(p interface{}) bool
CanMatch returns true if pattern p can be handled
func (*EmailMatcher) Match ¶ added in v1.1.0
func (m *EmailMatcher) Match(p, v interface{}) (bool, error)
Match performs value matching against given pattern.
type JSONMatcher ¶
type JSONMatcher struct {
// contains filtered or unexported fields
}
A JSONMatcher provides Match method to match two JSONs with pattern matching support.
func NewDefaultJSONMatcher ¶
func NewDefaultJSONMatcher() *JSONMatcher
NewDefaultJSONMatcher creates JSONMatcher with default chain of value matchers. Default chain contains:
- StringMatcher handling "@string@" pattern
- NumberMatcher handling "@number@" pattern
- BoolMatcher handling "@bool@" pattern
- ArrayMatcher handling "@array@" pattern
- UUIDMatcher handling "@uuid@" pattern
- EmailMatcher handling "@email@" pattern
- WildcardMatcher handling "@wildcard@" pattern
func NewJSONMatcher ¶
func NewJSONMatcher(matcher ValueMatcher) *JSONMatcher
NewJSONMatcher creates JSONMatcher with given value matcher.
func (*JSONMatcher) Match ¶
func (m *JSONMatcher) Match(expectedJSON, actualJSON string) (bool, error)
Match performs deep match of given JSON with an expected JSON pattern.
It traverses expected JSON pattern and checks if actual JSON has expected values. When traversing it checks if expected value is a pattern supported by internal ValueMatcher. In such case it uses the ValueMatcher to match actual value otherwise it compares expected value with actual value.
Expected JSON pattern example:
{
"id": "@number@",
"name": "John Smith",
"address": {
"city": "@string@"
}
}
Matching actual JSON:
{
"id": 351,
"name": "John Smith",
"address": {
"city": "Boston"
}
}
In above example we assume that ValueMatcher supports "@number@" and "@string@" patterns, otherwise matching will fail.
Besides value patterns JSONMatcher supports an "unbounded pattern" - "@...@". It can be used at the end of an array to allow any extra array elements:
[ "John Smith", "Joe Doe", "@...@" ]
It can be used at the end of an object to allow any extra keys:
{
"id": 351,
"name": "John Smith",
"@...@": ""
}
When matching fails then error message contains a path to invalid value.
type NumberMatcher ¶
type NumberMatcher struct {
// contains filtered or unexported fields
}
A NumberMatcher matches float64. It expects float64 because json.Unmarshal uses float64 by default for numbers.
func NewNumberMatcher ¶
func NewNumberMatcher(pattern string) *NumberMatcher
NewNumberMatcher creates NumberMatcher.
func (*NumberMatcher) CanMatch ¶
func (m *NumberMatcher) CanMatch(p interface{}) bool
CanMatch returns true if pattern p can be handled
func (*NumberMatcher) Match ¶
func (m *NumberMatcher) Match(p, v interface{}) (bool, error)
Match performs value matching against given pattern.
type StringMatcher ¶
type StringMatcher struct {
// contains filtered or unexported fields
}
A StringMatcher matches any string
func NewStringMatcher ¶
func NewStringMatcher(pattern string) *StringMatcher
NewStringMatcher creates StringMatcher.
func (*StringMatcher) CanMatch ¶
func (m *StringMatcher) CanMatch(p interface{}) bool
CanMatch returns true if pattern p can be handled.
func (*StringMatcher) Match ¶
func (m *StringMatcher) Match(p, v interface{}) (bool, error)
Match performs value matching against given pattern.
type UUIDMatcher ¶
type UUIDMatcher struct {
// contains filtered or unexported fields
}
A UUIDMatcher matches booleans.
func NewUUIDMatcher ¶
func NewUUIDMatcher(pattern string) *UUIDMatcher
NewUUIDMatcher creates UUIDMatcher.
func (*UUIDMatcher) CanMatch ¶
func (m *UUIDMatcher) CanMatch(p interface{}) bool
CanMatch returns true if pattern p can be handled
func (*UUIDMatcher) Match ¶
func (m *UUIDMatcher) Match(p, v interface{}) (bool, error)
Match performs value matching against given pattern.
type ValueMatcher ¶
type ValueMatcher interface {
// CanMatch returns true if given pattern can be handled by value matcher implementation.
CanMatch(p interface{}) bool
// Match performs the matching of given value v.
// It also expects pattern p so implementation may handle multiple patterns or some DSL.
Match(p, v interface{}) (bool, error)
}
A ValueMatcher interface should be implemented by any matcher used by JSONMatcher.
type WildcardMatcher ¶
type WildcardMatcher struct {
// contains filtered or unexported fields
}
A WildcardMatcher matches any value.
func NewWildcardMatcher ¶
func NewWildcardMatcher(pattern string) *WildcardMatcher
NewWildcardMatcher creates WildcardMatcher.
func (*WildcardMatcher) CanMatch ¶
func (m *WildcardMatcher) CanMatch(p interface{}) bool
CanMatch returns true if pattern p can be handled
func (*WildcardMatcher) Match ¶
func (m *WildcardMatcher) Match(p, v interface{}) (bool, error)
Match return true for any value
Source Files