Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 25 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
Welcome to use `atest` to improve your code quality.

## Get started

You can use `atest` as a CLI or as:

* Web UI
Expand All @@ -15,6 +16,7 @@ See also the screenshots below:
![image](https://github.com/LinuxSuRen/api-testing/assets/1450685/e959f560-1fb5-4592-9f45-ec883c385785)

## Installation

There are various ways of installing `atest`:

* CLI via `hd i atest`
Expand All @@ -34,7 +36,7 @@ Currently, it supports the following kinds of services:

[![Deployed on Zeabur](https://zeabur.com/deployed-on-zeabur-dark.svg)](https://zeabur.com?referralCode=LinuxSuRen&utm_source=LinuxSuRen&utm_campaign=oss)

### Have a look at the following example usage:
### Have a look at the following example usage

#### Podman

Expand All @@ -43,13 +45,14 @@ sudo atest service install -m podman --version master
```

#### Docker

```shell
docker run -v /var/www/sample:/var/www/sample \
--network host \
linuxsuren/api-testing:master
```

The default web server port is `8080`. So you can visit it via: http://localhost:8080
The default web server port is `8080`. So you can visit it via: <http://localhost:8080>

## Run in k3s

Expand All @@ -62,6 +65,7 @@ kustomize build sample/kubernetes/docker.io/ | k3s kubectl apply -f -
```

## Run your test cases

The test suite file could be local, or in the HTTP server. Have a look at some examples:

* `atest run -p your-local-file.yaml`
Expand Down Expand Up @@ -107,6 +111,7 @@ items:
You can use all the functions that are available in the expr library.

## Convert to JMeter

[JMeter](https://jmeter.apache.org/) is a load test tool. You can run the following commands from the root directory of this repository:

```shell
Expand All @@ -118,6 +123,7 @@ jmeter -n -t bin/gitee.jmx
Please feel free to bring more test tool converters.

## Run in Jenkins

You can run the API testings in Jenkins, as demonstrated in the example below:

```Jenkinsfile
Expand All @@ -140,9 +146,11 @@ pipeline {
```

## Report

You can see the test results in [Grafana](prometheus.md).

## Monitoring

It can monitor the server and browser via the [Apache SkyWalking](https://skywalking.apache.org/).
Please add the following flag if you want to get the browser tracing data:

Expand All @@ -156,6 +164,7 @@ atest server --skywalking http://localhost:12800
```

## Storage

There are multiple storage backends supported. See the status from the list:

| Name | Status |
Expand All @@ -168,6 +177,7 @@ There are multiple storage backends supported. See the status from the list:
| MongoDB | Devloping |

### Local Storage

Local storage is the built-in solution. You can run it with the following command:

```shell
Expand All @@ -185,11 +195,13 @@ atest server --local-storage 'sample/*.yaml' --console-path console/atest-ui/dis
```

Use the host network mode if you want to connect to your local environment:

```shell
podman run --pull always --network host ghcr.io/linuxsuren/api-testing:master
```

### ORM Database Storage

Start a database with the following command if you don't have a database already. You can install [tiup](https://tiup.io/) via `hd i tiup`.

```shell
Expand Down Expand Up @@ -222,6 +234,7 @@ podman run -p 7071:7071 \
```

### S3 Storage

You can use a S3 compatible storage as the storage backend.

```shell
Expand Down Expand Up @@ -249,6 +262,7 @@ Have a look at the expected configuration below:
```

### Git Storage

You can use a git repository as the storage backend.

```shell
Expand All @@ -275,6 +289,7 @@ Have a look at the expected configuration below:
```

### MongoDB Storage

You can use a MongoDB as the storage backend.

Have a look at the expected configuration below:
Expand All @@ -292,6 +307,7 @@ Have a look at the expected configuration below:
```

## Secret Server

You can put sensitive information into a secret server. For example, [Vault](https://www.github.com/hashicorp/vault).

Connect to [a vault extension](https://github.com/LinuxSuRen/api-testing-secret-extension) via flag: `--secret-server`. Such as:
Expand All @@ -301,6 +317,7 @@ atest server --secret-server localhost:7073
```

## Application monitor

You can get the resource usage in the report through Docker:

```shell
Expand All @@ -311,19 +328,22 @@ atest run -p sample/testsuite-gitlab.yaml --monitor-docker test --report md

| Item | Description |
|---|---|
| `expect.bodyFieldsExpect` | See also the syntax from https://github.com/tidwall/gjson |
| `expect.bodyFieldsExpect` | See also the syntax from [gjson](https://github.com/tidwall/gjson) |

## OAuth

It support GitHub, [Dex](https://github.com/dexidp/dex) as OAuth provider. See also the following usage:

```shell
atest server --auth oauth --client-id your-id --client-secret your-secret
```

## Extensions

Developers can have storage, secret extensions. Implementing a gRPC server according to [loader.proto](../pkg/testing/remote/loader.proto) is required.

## Official Images

You can find the official images from both [Docker Hub](https://hub.docker.com/r/linuxsuren/api-testing) and others. See the image path:

* `ghcr.io/linuxsuren/api-testing:master`
Expand All @@ -335,11 +355,13 @@ You can find the official images from both [Docker Hub](https://hub.docker.com/r
The tag `latest` represents the latest release version. The tag `master` represents the image of the latest master branch. We highly recommend you to use a fixed version instead of those in a production environment.

## Release Notes

* [v0.0.15](release-note-v0.0.15.md)
* [v0.0.14](release-note-v0.0.14.md)
* [v0.0.13](release-note-v0.0.13.md)
* [v0.0.12](release-note-v0.0.12.md)

## Articles

* [Introduction](introduce-zh.md)
* [GLCC 2023 announccement](glcc-2023-announce.md)
Loading