• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号

matryer/silk: Markdown based document-driven RESTful API testing.

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

matryer/silk

开源软件地址(OpenSource Url):

https://github.com/matryer/silk

开源编程语言(OpenSource Language):

Go 97.3%

开源软件介绍(OpenSource Introduction):

Silk logo

silk Build Status Go Report Card

Markdown based document-driven web API testing.

Learn more

Video of Mat Ryer speaking about Silk

(VIDEO) Watch the talk about Silk (with slides) or read about Silk in this blog post.

Example Silk test file

Markdown API

Tests are made up of documents written in Markdown.

  • # Group - Top level headings represent groups of requests
  • ## GET /path - Second level headings represent a request
  • Code blocks with three back tics represent bodies
  • * Field: value - Lists describe headers and assertions
  • * ?param=value - Request parameters
  • --- seperators break requests from responses
  • Comments (starting with //) allow you to capture variables
  • Plain text is ignored to allow you to add documentation
  • Inline back tics are ignored and are available for formatting

Document structure

A document is made up of:

  • A request
  • --- seperator
  • Assertions

Requests

A request starts with ## and must have an HTTP method, and a path:

## METHOD /path

Examples include:

## GET /people

## POST /people/1/comments

## DELETE /people/1/comments/2

Request body (optional)

To specify a request body (for example for POST requests) use a codeblock using backtics (```):

```
{"name": "Silk", "release_year": 2016}
```

Request headers (optional)

You may specify request headers using lists (prefixed with *):

* Content-Type: "application/json"
* X-Custom-Header: "123"

Request parameters (optional)

Adding parameters to the path (like GET /path?q=something) can be tricky, especially when you consider escaping etc. To address this, Silk supports parameters like lists:

* ?param=value

The parameters will be correctly added to the URL path before the request is made.

Cookies

Setting cookies on a request can be done using the HTTP header pattern:

* Cookie: "key=value"

Assertions

Following the --- separator, you can specify assertions about the response. At a minimum, it is recommended that you assert the status code to ensure the request succeeded:

* Status: 200

You may also specify response headers in the same format as request headers:

* Content-Type: "application/json"
* X-MyServer-Version: "v1.0"

If any of the headers do not match, the test will fail.

Capturing data

Silk allows you to capture values at the point of asserting them and reuse them in future requests and assertions. To capture a value, include a comment on the line that mentions a {placeholder}:

* Data.UserID: /.*/ // The user's unique {id}.

The value from UserID (e.g. 123) will be stored in a variable called id, and you can refer to it later:

## GET /users/{id}

The above would be a request to GET /users/123.

  • Captured values are only available when assertions are successful

Environment variables

You can access environment variables inside Silk tests using the {$NAME} format, where NAME is the environment name.

Asserting cookies

To assert that a cookie is present in a response, make a regex assertion against the Set-Cookie HTTP header:

* Set-Cookie: /key=value/
  • All cookie strings are present in a single Set-Cookie seperated by a pipe character.

Validating data

You can optionally include a verbatim body using code blocks surrounded by three back tics. If the response body does not exactly match, the test will fail:

```
Hello world!
```

You can flag expected response bodies as json directly after the three back tics. This will assert that the actual response contains the same value for each expected key (recursively) allowing for differences in whitespace and ordering as well as being lenient towards additional (unexpected) keys in the response.

```json
{
    "id": 1,
    "release_year": 2016,
    "name": "Silk"
}
```

You can use the flag json(strict) to enforce that no additional fields may be present while still allowing for differences in whitespace and key order.

You may also make any number of regex assertions against the body using the Body object:

* Body: /Hello world/
* Body: /This should be found too/
* Body: /and this/

Alternatively, you can specify a list (using *) of data fields to assert accessible via the Data object:

* Status: 201
* Content-Type: "application/json"
* Data.name: "Silk"
* Data.release_year: 2016
* Data.tags[0]: "testing"
* Data.tags[1]: "markdown"
* Data[0].name: "Mat"
* Data[1].name: "David"
  • NOTE: Currenly this feature is only supported for JSON APIs.

Regex

Values may be regex, if they begin and end with a forward slash: /. The assertion will pass if the value (after being turned into a string) matches the regex.

* Status: /^2.{2}$/
* Content-Type: /application/json/

The above will assert that:

  • The status looks like 2xx, and
  • The Content-Type contains application/json

Command line

The silk command runs tests against an HTTP endpoint.

Usage:

silk -silk.url="{endpoint}" {testfiles...}
  • {endpoint} the endpoint URL (e.g. http://localhost:8080)
  • {testfiles} list of test files (e.g. ./testfiles/one.silk.md ./testfiles/two.silk.md)

Notes:

  • Omit trailing slash from endpoint
  • {testfiles} can include a pattern (e.g. /path/*.silk.md) as this is expended by most terminals to a list of matching files

Golang

Silk is written in Go and integrates seamlessly into existing testing tools and frameworks. Import the runner package and use RunGlob to match many test files:

package project_test

import (
  "testing"
  "github.com/matryer/silk/runner"
)

func TestAPIEndpoint(t *testing.T) {
  // start a server
  s := httptest.NewServer(yourHandler)
  defer s.Close()

  // run all test files
  runner.New(t, s.URL).RunGlob(filepath.Glob("../testfiles/failure/*.silk.md"))
}

Credit

  • Special thanks to @dahernan for his contributions and criticisms of Silk
  • Silk logo by Chris Ryer



鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
TooBug/wemark: 微信小程序Markdown渲染库发布时间:2022-08-18
下一篇:
jrainlau/markcook: A smart and beautiful markdown editor.发布时间:2022-08-18
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap