2023-12-02 19:16:33 +08:00
[![CLA assistant ](https://cla-assistant.io/readme/badge/LinuxSuRen/api-testing )](https://cla-assistant.io/LinuxSuRen/api-testing)
2023-10-27 19:48:18 +08:00
[![Codacy Badge ](https://app.codacy.com/project/badge/Grade/3f16717cd6f841118006f12c346e9341 )](https://app.codacy.com/gh/LinuxSuRen/api-testing/dashboard?utm_source=gh& utm_medium=referral& utm_content=& utm_campaign=Badge_grade)
[![Codacy Badge ](https://app.codacy.com/project/badge/Coverage/3f16717cd6f841118006f12c346e9341 )](https://app.codacy.com/gh/LinuxSuRen/api-testing/dashboard?utm_source=gh& utm_medium=referral& utm_content=& utm_campaign=Badge_grade)
2024-03-13 09:27:01 +08:00
[![GitHub All Releases ](https://img.shields.io/github/downloads/linuxsuren/api-testing/total )](https://tooomm.github.io/github-release-stats/?username=linuxsuren& repository=api-testing)
[![Docker Pulls ](https://img.shields.io/docker/pulls/linuxsuren/api-testing )](https://hub.docker.com/r/linuxsuren/api-testing)
2023-05-09 21:41:46 +08:00
[![LinuxSuRen/open-source-best-practice ](https://img.shields.io/static/v1?label=OSBP&message=%E5%BC%80%E6%BA%90%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5&color=blue )](https://github.com/LinuxSuRen/open-source-best-practice)
2023-03-05 11:32:27 +08:00
2024-05-09 10:14:22 +08:00
> English | [中文](README-ZH.md)
2024-07-30 18:34:26 +08:00
This is an awesome API testing tool. 🚀
2023-03-05 11:32:27 +08:00
2023-05-18 09:51:35 +08:00
## Features
2023-04-12 13:31:52 +08:00
2024-04-23 11:36:50 +08:00
* Supported protocols: HTTP, gRPC, tRPC
* Multiple test report formats: Markdown, HTML, PDF, Stdout
2024-04-30 14:06:15 +08:00
* Mock Server in simple configuration, and Open API support
2024-04-23 11:36:50 +08:00
* Support converting to [JMeter ](https://jmeter.apache.org/ ) files
* Response Body fields equation check or [eval ](https://expr.medv.io/ )
* Validate the response body with [JSON schema ](https://json-schema.org/ )
* Pre and post handle with the API request
* Run in server mode, and provide the [gRPC ](pkg/server/server.proto ) and HTTP endpoint
* [VS Code extension ](https://github.com/LinuxSuRen/vscode-api-testing ) support
* Multiple storage backends supported(Local, ORM Database, S3, Git, Etcd, etc.)
* [HTTP API record ](https://github.com/LinuxSuRen/atest-ext-collector )
* Install in multiple use cases(CLI, Container, Native-Service, Operator, Helm, etc.)
* Monitoring integration with Prometheus, SkyWalking
2023-04-12 13:31:52 +08:00
## Get started
2024-05-09 16:32:17 +08:00
[![Try in PWD ](https://github.com/play-with-docker/stacks/raw/cff22438cb4195ace27f9b15784bbb497047afa7/assets/images/button.png )](http://play-with-docker.com?stack=https://raw.githubusercontent.com/LinuxSuRen/api-testing/master/docs/manifests/docker-compose.yml)
2023-11-26 13:29:31 +08:00
2023-04-12 13:31:52 +08:00
Install it via [hd ](https://github.com/LinuxSuRen/http-downloader ) or download from [releases ](https://github.com/LinuxSuRen/api-testing/releases ):
```shell
hd install atest
```
2023-10-27 17:26:23 +08:00
or, you can install it in Kubernetes. See also the [manifests ](docs/manifests/kubernetes/default/manifest.yaml ).
2023-05-31 23:08:25 +08:00
2023-04-12 13:31:52 +08:00
see the following usage:
```shell
API testing tool
Usage:
atest [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
2023-06-14 10:32:28 +08:00
func Print all the supported functions
2023-04-12 13:31:52 +08:00
help Help about any command
json Print the JSON schema of the test suites struct
run Run the test suite
sample Generate a sample test case YAML file
server Run as a server mode
2023-06-14 10:32:28 +08:00
service Install atest as a Linux service
2023-04-12 13:31:52 +08:00
Flags:
-h, --help help for atest
-v, --version version for atest
Use "atest [command] --help" for more information about a command.
```
below is an example of the usage, and you could see the report as well:
2023-04-20 17:49:00 +08:00
`atest run -p sample/testsuite-gitlab.yaml --duration 1m --thread 3 --report md`
2023-04-12 13:31:52 +08:00
| API | Average | Max | Min | Count | Error |
|---|---|---|---|---|---|
| GET https://gitlab.com/api/v4/projects | 1.152777167s | 2.108680194s | 814.928496ms | 99 | 0 |
| GET https://gitlab.com/api/v4/projects/45088772 | 840.761064ms | 1.487285371s | 492.583066ms | 10 | 0 |
consume: 1m2.153686448s
2023-03-05 11:32:27 +08:00
2023-06-08 17:27:40 +08:00
## Use in Docker
2023-07-21 18:47:11 +08:00
Use `atest` as server mode in Docker, then you could visit the UI from `8080` :
2024-04-23 11:36:50 +08:00
```bash
2023-07-21 18:47:11 +08:00
docker run --pull always -p 8080:8080 ghcr.io/linuxsuren/api-testing:master
2023-06-08 17:27:40 +08:00
```
Use `atest-collector` in Docker:
2024-04-23 11:36:50 +08:00
```bash
2023-06-08 17:27:40 +08:00
docker run -p 1234:8080 -v /var/tmp:/var/tmp \
ghcr.io/linuxsuren/api-testing atest-collector \
--filter-path /api \
-o /var/tmp/sample.yaml
# you could find the test cases file from /var/tmp/sample
# cat /var/tmp/sample
```
2023-03-05 11:32:27 +08:00
## Template
2023-04-12 13:31:52 +08:00
2023-03-05 11:32:27 +08:00
The following fields are templated with [sprig ](http://masterminds.github.io/sprig/ ):
2024-04-23 11:36:50 +08:00
* API
* Request Body
* Request Header
2023-03-10 15:42:19 +08:00
2023-04-24 12:20:49 +08:00
### Functions
You could use all the common functions which comes from [sprig ](http://masterminds.github.io/sprig/ ). Besides some specific functions are available:
| Name | Usage |
|---|---|
| `randomKubernetesName` | `{{randomKubernetesName}}` to generate Kubernetes resource name randomly, the name will have 8 chars |
2023-05-18 09:51:35 +08:00
| `sleep` | `{{sleep(1)}}` in the pre and post request handle |
2023-04-24 12:20:49 +08:00
2023-04-15 21:47:50 +08:00
## Verify against Kubernetes
It could verify any kinds of Kubernetes resources. Please set the environment variables before using it:
2024-04-23 11:36:50 +08:00
* `KUBERNETES_SERVER`
* `KUBERNETES_TOKEN`
2023-04-15 21:47:50 +08:00
See also the [example ](sample/kubernetes.yaml ).
2023-03-10 15:42:19 +08:00
## TODO
2023-04-12 13:31:52 +08:00
2024-04-23 11:36:50 +08:00
* Reduce the size of context.
* Support customized context.
2023-03-05 11:32:27 +08:00
## Limit
2023-04-12 13:31:52 +08:00
2024-04-23 11:36:50 +08:00
* Only support to parse the response body when it's a map or array.
## Community Exchange
Feel free to talk to us about any questions you may have about API Testing in the following ways.
### Mailing List
`api-testing-tech@googlegroups.com` , Feel free to discuss everything related to API Testing via this mailing list.
2024-04-30 14:06:15 +08:00
### `GitHub` discussion
2024-04-23 11:36:50 +08:00
2024-04-30 14:06:15 +08:00
[GitHub Discussion ](https://github.com/LinuxSuRen/api-testing/discussions/new/choose )