Aloe is a declarative API test framework based on ginkgo, gomega and yaml. It aims to help write and read API test cases simpler.
DISCLAIMER:
- only json API is supported now
- avoid using Aloe for extremely complex test, use ginkgo directly instead
There are two important concepts in aloe:
case: case means a test case, for example, get an endpoint and verify its output.context: to simply put, a context is a group of cases. Usually, context is used to init data in database, so that all test cases will be tested in a determined context.
Following is a getting started example for using Aloe. First, create a
directory to put context and case yaml files.
mkdir -p test/testdata
Then, define your context in context.yaml.
# test/testdata/context.yaml
summary: "CRUD Test example"
flow:
- description: "Init a product"
request:
api: POST /products
headers:
"Content-Type": "application/json"
body: |
{
"id": "1",
"title": "test"
}
response:
statusCode: 201
definitions:
- name: "testProductId"
selector:
- "id"As mentioned above, a context is used to run a group of test cases in a
determined environment. In the above example,
we define a context which simply sends a POST request to /products with
product name test; therefore, all test
cases in this context will expect product test exists.
Now with context setup, we can start defining case. Here, we define a test
case in test/testdata/get.yaml to get
and verify product test.
# test/testdata/get.yaml
description: "Try to GET a product"
flow:
- description: "Get the product with title test"
request:
api: GET /products/%{testProductId}
headers:
"Content-Type": "application/json"
response:
statusCode: 200Finally, some go codes should be written in test directory to run the test
case:
func init() {
aloe.Init(nil)
}
func RunTEST(t *testing.T) {
aloe.AppendDataDirs("testdata")
if err := aloe.Env("host", "localhost:8080"); err != nil {
fmt.Printf("can't set env host: %v", err)
os.Exit(1)
}
if err := aloe.RegisterCleaner(s); err != nil {
fmt.Printf("can't register cleaner: %v", err)
os.Exit(1)
}
aloe.Run(t)
}
var _ = ginkgo.BeforeSuite(func() {
s.Register()
listener, err := net.Listen("tcp", ":8080")
if err != nil {
fmt.Println("can't begin server")
os.Exit(1)
}
go http.Serve(listener, nil)
})Variables can be defined to hold auto-generated value by server (e.g. id). For example:
flow:
- description: "Init a product"
definitions:
- name: "testProductId"
selector:
- "id"A variable called testProductId will be defined. The value of testProductId
is from the round trip response.
Variable can also be a json snippet.
response:
{
"id": "111",
"title": "test",
"comments":[
"aaa",
"bbb"
]
}
// id will select value of string
["id"] => 111(without quote)
// empty selector will select whole body
[] => {
"id": "111",
"title": "test",
"comments":[
"aaa",
"bbb"
]
}
// comments will select partial body
["comments"] => [
"aaa",
"bbb"
]
// comments.0 will select first element of array
["comments", "0"] => aaa
If a variables is defined, it can be used in round trip with format %{name}.
Body validator is used to validate response fields. Some special validators are
predefined, e.g. $regexp
flow:
- description: "Create a product"
response:
# validate that id format matches regexp
# validate that password field is not returned
body: |
{
"id": {
"$regexp": "[a-zA-Z][a-zA-Z0-9-]{11}"
},
"password": {
"$exists": false,
},
}Now only $regexp and $exists is supported (more special validator will be
added in the future).
Cleaner can be used to clean context after all cases in the context are finished.
type Cleaner interface {
// Name defines cleaner name
Name() string
// Clean will be called after all of the cases in the context are
// finished
Clean(variables map[string]jsonutil.Variable) error
}Users can implement their own cleaners and call RegisterCleaner in framework. Then cleaners can be used in context file.
# test/testdata/get.yaml
summary: "Create a product"
flow:
- description: "Create a product"
request:
api: POST /products
response:
statusCode: 201
cleaner: "productCleaner"Presetter can be used to preset all RoundTrips in the context.
// Presetter defines presetter
type Presetter interface {
// Name defines name of presetter
Name() string
// Preset parse args and set roundtrip template
Preset(rt *types.RoundTrip, args map[string]string) (*types.RoundTrip,
error)
}Users can implement their own presetters and call RegisterPresetter in framework. Then presetters can be used in context file.
# test/testdata/get.yaml
summary: "Create a product"
presetter:
- name: "header"
args:
content-type: application/json
flow:
- description: "Create a product"
request:
api: POST /products
response:
statusCode: 201Context can be nested just like directory. Child context will see all setup in parent context.
tests
└── testdata
├── _context.yaml
├── basic
│ ├── _context.yaml
│ ├── create.yaml
│ └── update.yaml
├── failure
│ ├── _context.yaml
│ └── create.yaml
└── list
├── _context.yaml
└── list_all.yaml
For more examples, see:
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent