# TestNgAPITest

**Repository Path**: louxj/TestNgAPITest

## Basic Information

- **Project Name**: TestNgAPITest
- **Description**: Open API自动化测试框架程序
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2019-04-25
- **Last Updated**: 2022-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目简介
## 项目来源
> 本项目来源于公司实际项目开发中衍生出来的Open API接口自动化测试框架程序，可基于此框架做二次开发。

## 项目用途
对于普通的开发人员，在没有测试人员参与项目的情况下，可以基于此项目做二次开发，通过设置定时任务的方式周期性地监控线上接口的可用性及功能的完整性。在减轻对于大型监控系统的重度依赖的同时，也填补了大型通用监控系统对于接口功能性测试的不足。


## 项目特点
- 支持按照部署环境区分测试数据，按照测试分组区分测试代码
- 支持测试统计结果以报表形式发送报警通知开发人员
- 支持多种测试方式：本地测试、IDE测试、打包测试
- 支持多种测试场景：CURD测试、场景测试
- 提供了MakeFile，支持快速构建、打包和部署

### 补充说明
1. 测试用例场景的说明：
- CURD测试用例场景：只涉及到单个对象增删改查接口的基本测试
- 场景测试用例场景：模拟用户真实的操作场景的、涉及多个操作对象的复杂测试

### 待完善的点
- [ ] 将单元测试和示例从主模块中剥离出来，使得代码结构更加清晰。 
- [ ] 添加测试用例CRUD的接口，将测试用例落库存储，从数据库从加载测试用例，可以使得该框架程序的通用性得到增强。 
- [ ] 报警渠道和报警模板的配置化。

# 关键技术
## Retrofit
基于Retrofit简化网络请求包的构建、发送和接收，因为它为所有的HTTP请求预定义好了规范的请求方法、请求头部、请求参数等。

Retrofit是一个RESTful的HTTP网络请求框架的封装，在Android网络请求库中，是当下最热的一个网络请求库。它是基于OkHttp实现的，即Retrofit 实际工作仅负责网络请求接口的封装，而网络请求的工作本质是OkHttp完成的。

整个demo框架中最核心的工作就是定义接口，Retrofit将Http请求抽象成Java接口：采用注解描述网络请求参数和配置网络请求参数，内部实现上采用动态代理动态地将该接口的注解增强为一个Http请求，最后再调用下层的OkHTTP库执行Http请求。

## Quartz
基于Quartz实现单机定时任务：实现了两个定时任务。定时任务`TestJob`以较短的间隔周期性执行，具体周期可以通过运行是添加`-Dcron`参数指定，结果写入到`DaliySummary`中，另外一个`DaliyTask`每天执行一次，将一天内所有`TestJob`写入到`DaliySummary`结果汇总后发送给开发人员。

下面简要介绍一下Quartz中的核心组件：

- 调度器：scheduler
> 任务调度的控制器，负责定时任务的调度，并且提供任务和触发器的增删改查等api方法。

- 任务：job
> job是实际被调度的任务，每个任务必须指定具体执行任务的实现类，实现类需要继承QuartzJobBean或者实现org.quartz.Job接口，具体的业务逻辑写在execute方法里面。
是否支持并发的注解：@DisallowConcurrentExecution

- 触发器：trigger
> trigger用来定义调度时间的概念，即按什么样时间规则去触发任务。

更多有关Quartz定时任务实现原理的介绍请戳:[Quartz原理分析](https://www.jianshu.com/p/e95d6764b4d9)


## TestNG
> TestNG是一个开源自动化测试框架;TestNG表示下一代(Next Generation的首字母)。 TestNG类似于JUnit(特别是JUnit 4)，但它不是JUnit框架的扩展。它的灵感来源于JUnit。它的目的是优于JUnit，尤其是在用于测试集成多类时.
- **支持多种配置注解**：规定测试方法（测试类中的某个方法）和组（不同测试类中多个测试方法）的执行顺序
- **支持分组测试、套件测试**：组测试提供了如何分区测试的最大灵活性、套件测试是用于测试软件程序的行为或一组行为的测试用例的集合
- **支持参数化测试**：在大多数情况下，会遇到业务逻辑需要大量测试的场景。参数化测试允许开发人员使用不同的值一次又一次地运行相同的测试。
- **支持多样化测测试场景和需求**：预期异常测试、忽略测试、超时测试、依赖测试

测试套件->测试分组->测试类->测试方法

测试套件->测试分组->测试类->测试方法

更多有关TestNG的使用教程请戳:[TestNG教程](https://www.yiibai.com/testng)

TestNG相对于Junt的主要区别在于提供了分组测试、套件测试以及参数化测试的功能，二者的详细对比可以参考下面的文章。[JUnit 4 Vs TestNG比较](https://www.yiibai.com/testng/junit-vs-testng-comparison.html)

## TODO
- 添加MakeFile中打包后上传文件服务器的功能
- 。。。


# 使用说明
## profile参数说明
标识符|环境
---|---
localhost|本地测试环境
online|线上环境


## VM启动参数说明
参数|说明
---|---
env|profile参数
cron|cron表达式，定义任务执行的时间节点
work.dir|conf等配置文件所在的目录


## 运行及打包说明
### 命令行方式运行
运行方式：
```
# env 表示 resource/conf 下的文件名（只保留前缀，不要后缀）
# suiteXmlFile 表示 resources/xml 文件夹下的测试文件名
mvn -Denv=localhost -DsuiteXmlFile=testBasic.xml test
```

测试结果的输出示例如下：
```
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.646 sec - in TestSuite

Results :

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
```

### IDEA中按钮启动
IDEA直接运行需要添加如下的VM参数：
```
-Denv=localhost -Dcron="0/10 * * * * ? *" -Dwork.dir=target
```

### 打包后本地运行
项目还可以被打成jar包，使用
```
mvn -Dmaven.test.skip=true package
```

打包后在target目录下，可以看到
```
target/
  |--conf/
  |--xml/
  |--configEnv
  |--TestNgAPITest-1.0-SNAPSHOT-jar-with-dependencies.jar
  ...
```
``` shell
# env 用于指定当前测试的Region环境
# work.dir 用于指定运行的目录，用于读取conf文件
java -Denv=localhost -Dcron="0/10 * * * * ? *" -Dwork.dir=target -jar target/TestNgAPITest-1.0-SNAPSHOT-jar-with-dependencies.jar
```

### 打包后上传服务运行

项目下面已经写好了Makefile，只要`make`一下(如果是windiows环境，请参数参考资料1安装相关软件，mac可以直接执行`make`指令)，就能在目录下生成`TestNgAPITest-$VERSION.tgz`的压缩包，上传到服务器上，解压缩后执行如下指令：

``` shell
# env 用于指定当前测试的Region环境
# work.dir 用于指定运行的目录，用于读取conf文件
# ${directory}为解压后的压缩文件所在路径
java -Denv=localhost -Dcron="0/10 * * * * ? *" -Dwork.dir=${directory} -jar ${directory}/TestNgAPITest-1.0-SNAPSHOT-jar-with-dependencies.jar
```

## 测试用例编写建议
测试用例场景主要分为两种：
- CURD测试用例场景：只涉及到单个对象增删改查接口的基本测试
- 场景测试用例场景：模拟用户真实的操作场景的、涉及多个操作对象的复杂测试

对于CURD类型的基本测试用例场景：
- 建议对于`create`和`delete`操作合并编写；
- 对于`update`和`get`的操作，需要预先创建好资源，`update`操作执行变更之后需要再`update`回来

## 自动化测试框架结构
   
![IMG20190124_110951.png](./pic/structure.png)

主要对package有差异的地方进行介绍：

|package  | 作用 |
|--------------|--------------|
|com.netease.cloud.cm.api  | API接口的封装，接口封装形式有变更，当新增或者接口有变化时，需修改接口定义 |
|com.netease.cloud.cm.retrofit.service  | 创建代理对象，然后使用代理对象对api接口进行调用，一般定义好之后无需再修改 |
|com.netease.cloud.cm.retrofit.logger  | 定义拦截器OkHttpLogger将日志输出到文本，无需修改 |

## 自动化测试框架使用方法

框架使用方法相对也比较简单，框架使用到的工具是Retrofit：

1. pom文件中添加Retrofit库的依赖
2. 创建API请求接口（参见com.netease.cloud.cm.api.CommonApi），具体使用方法后续会单独进行讲解
3. 创建Retrofit实例：设置请求Url地址、设置数据解析器等（参见com.netease.cloud.cm.retrofit.service.RetrofitManager）
4. 发送网络请求，对返回的数据进行处理（参见com.netease.cloud.cm.testcase）

# 关键技术点介绍
## Retrofit

Retrofit是一个RESTful的HTTP网络请求框架的封装，在Android网络请求库中，是当下最热的一个网络请求库。它是基于OkHttp实现的，即Retrofit 实际工作仅负责网络请求接口的封装，而网络请求的工作本质是OkHttp完成的。

![Retrofit.png](./pic/Retrofit.png)

- demo中程序通过Retrofit请求网络，实际上是使用 Retrofit 接口层封装请求参数、Header、Url 等信息，之后由 OkHttp 完成后续的请求操作
- 在服务端返回数据之后，OkHttp 将原始的结果交给 Retrofit，Retrofit根据用户的需求对结果进行解析

整个demo框架中最核心的工作就是定义接口，Retrofit将Http请求抽象成Java接口：采用注解描述网络请求参数和配置网络请求参数

1. 原理：用动态代理 动态 将该接口的注解“翻译”成一个Http请求，最后再执行Http请求 
2. 注意：接口中的每个方法的参数都需要使用注解标注，否则会报错

Retrofit网络请求接口的注解类型如下：

![retrofit1.png](./pic/annotations.png)

### 1.网络请求方法

![retrofit2.png](./pic/http.png)

a. @GET、@POST、@PUT、@DELETE、@HEAD 以上方法分别对应HTTP中的网络请求方式

网络请求的完整Url=在创建Retrofit实例时通过.baseUrl()设置 + 网络请求接口的注解设置

```java
//静态添加header
@Headers("Accept:application/json")
@GET("ncr?Action=GetCurrentVersion&Version=2018-03-22")
Call<DescribeServiceVersionResponse> getCurrentVersion();

// 动态添加header
@HTTP(method = "GET", path = "ncr?Action=DescribeRedis&Version=2018-03-22", hasBody = false)
Call<DescribeRedisResponse> describeRedis(@HeaderMap Map<String, String> headers,
                                         @Query("RedisId") String redisId);
```

b. @HTTP

为了方便扩展，可统一使用@HTTP进行替换@GET、@POST、@PUT、@DELETE、@HEAD注解的作用及更多功能拓展，通过属性method、path、hasBody进行设置

```java
@HTTP(method = "GET", path = "ncr?Action=GetCurrentVersion&Version=2018-03-22", hasBody = false)
Call<DescribeServiceVersionResponse> getCurrentVersion2(@HeaderMap Map<String, String> headers);
```

### 2.标记

![retrofit3.png](./pic/tag.png)

### 3.网络请求参数

![retrofit4.png](./pic/network.png)


# 参考资料
1. [windows 下使用make命令，编译代码](https://blog.csdn.net/nicholas_liu2017/article/details/78323391)
2. [Retrofit官方文档](https://square.github.io/retrofit/)
3. [Retrofit2.0使用教程](https://blog.csdn.net/carson_ho/article/details/73732076)
4. [TestNG教程](https://www.yiibai.com/testng)
5. [TestNG之测试方法依赖关系](https://blog.csdn.net/qq_40014593/article/details/87799528)