# xlsunit

**Repository Path**: eddylapis/xlsunit

## Basic Information

- **Project Name**: xlsunit
- **Description**: 公司研发中产出的一个工具，用于单元测试
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 36
- **Created**: 2017-07-01
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xlsunit

面向数据库应用的单元测试框架,使用excel,作为输入,以及输出比较,适合大量数据库操作.
如下情况可以使用xlsunit

* 必须使用Spring或者Spring Boot，因为会利用Spring单元测试事务回滚机制
* 面向数据库应用，特别是一个业务操作，有多个表的变化。

xlsunit支持Spring 4以上，SpringBoot1.5以上，支持Oracle，MySql，Postgres等数据库



#  为什么要使用XLSUnit

 面向数据应用的单元测试中，最麻烦的地方有俩个

* 模拟单元测试前的数据
* 以及单元测试后，比较数据库的数据是否是期望的数据。

Spring的面向数据库单元测试技术技术会有如下问题


* 用SQL脚本模拟数据库的初始化数据，不够直观，修改起来也费劲
* SQL脚本里的数据会在单元测试里使用，只能硬编码，缺少引用SQL脚本里的值办法
* 单元测试结束后需要比较是否与期望值一致，在Spring里，主要还是得靠写代码比较，会有大量的代码，容易出错，且不直观


DBUnit 是另外款单元测试工具一定程度上弥补了Spring面向数据库单元测试不足地方，通过XML来模拟和比较数据。但是模拟和比较数据都非常不直观，既然是面向数据库单元测试，为什么不能用xls初始化要测试前的数据，并且还用xls来比较单元测试后的期望数据呢？

XLSUnit正是基于这个想法，他可以用一个工作表容易的模拟数据表数据，在单元测试前，导入到一个空数据库，单元测试完毕，可以将数据库里的数据与另外一个工作表的数据做比较，如果只关心部分数据比较，只需要将这部分数据背景用红色填充，XLSUnit会只比较你关心的数据




# 安装



然后在项目里引用

		<dependency>
			<groupId>com.ibeetl</groupId>
			<artifactId>xlsunit</artifactId>
			<version>${version}</version>
			<scope>test</scope>
		</dependency>


​		

# 编写工作表

## excel

可以将测试数据写在excel里，或者通过数据库客户端工具粘贴到excel里完成数据的输入。

可以用拥有任意多个excel文件，每个文件概念上都可以包含一个初始化数据的多种测试场景，Excel文件有三部分组成

* 第一个工作表，这个工作表用来介绍当前excel文件所测试的业务，以及包含一个目录，快捷指向每个场景测试
* 第二个表示 数据库初始化数据，可以包含多个表的初始化数据，也可以在初始化数据定义前，定义一些变量，这些变量可以用在初始化数据，JUnit代码里，以及随后的场景测试里
* 第三个表以后的每个工作表都是场景测试表，对应了单元测试完毕后，期望的数据库的样子。通常用红色背景标注在表的列名上，这样表示只让XLSUnit比较关心的列。同时，也能提醒阅读者，编写期望值



如下是一些例子

* 第一个工作表，用于目录索引

![Alt text](doc/index.png)



* 输入sheet，用来初始化数据和变量


![Alt text](doc/input.png)

* 场景1,在某个单元测试完毕，按照主键比较数据库的值，红色部分是需要比较的部分


![Alt text](doc/case1.png)

XLSUnit会根据$id的值查询数据库，并与Excel里期望的数据做比较



* 场景二，比较一系列数据，比如主订单的所有子订单项

![Alt text](doc/case3.png)

表名后下一个单元格是单表查询条件语句，XLSUnit会查询数据库数据，并与下面的excel数据逐一比较

> XLSUnit 对excel里的数据的颜色不做限定，你可以使用任何颜色来分块，区分你的数据，除了列名上的红色，这个颜色用来表示仅仅比较期望的的列。这在XLSUnit是必须的。



## 编写目录表

目录表示excel的第一个工作区，可以是任意内容。比如可以介绍一下这个excel所代表的单元测试内容，单元测试代码类（好通过excel来找到单元测试），以及可以建立一些超链接，链接到每个场景测试

## 编写输入

### 编写注释

符号“##:” 通常出现一行的第一个单元格里，用来注释，XLSUnit会忽略这一行内容

| ##:这是一个注释 |      |      |      |      |
| --------- | ---- | ---- | ---- | ---- |
|           |      |      |      |      |

### 编写变量

符号"##" +小写变量名 定义了一组变量，这组变量可以在随后模拟数据库数据的时候使用，也可以在Java代码里复用（解决Spring @Sql的问题)，单元格的类型决定了数据类型。尤其要注意字符和数字的区别

| ##user   |      |          |      |      |
| -------- | ---- | -------- | ---- | ---- |
| name     | age  | bir      |      |      |
| xiandafu | 1    | $fn.date |      |      |

### 初始化数据库数据

符号"##"+大写变量名 定义了一个表格数据，其下一行是列名字，列名的后面所有行都是数据。  

| ##SYS_USER |            |           |        |      |
| ---------- | ---------- | --------- | ------ | ---- |
| ID         | NAME       | BIR       | GENDER |      |
| $id        | $user.name | $user.bir | 1      |      |
|            |            |           |        |      |

### 分割符号

可以定义多个变量组，还有多个数据库表，用空行分开。

### $符号和 # 符号说明

$符号有其特殊含义

* 用在列名上，表示是一个主键（尽管可以通过数据库MetaData自动判断，但为了好阅读，显示的标注一下还是很好的
* 用在单元格力，表示这是一个表达式，如 $fn.date, 表示一个当前时间，复杂的表达式要用${}.符合beetl表达式习惯
* 通常在数据库表里，$id 这样的变量如果不存在，表达的意思是需要回填。比如数据库自增主键，或者通过触发器，其他方式初始化的数据库数据。
* ${ } 对应于一个表达式，同Beetl，如${user.gender==1?"男" :"女"}


* sql语句类似Beetlsql，可以使用变量，比如在批量比较里，使用##符号来引用变量


| ##SYS_USER | NAME=#user.name# order by id ASC |      |        |      |
| ---------- | -------------------------------- | ---- | ------ | ---- |
| ID         | NAME                             | BIR  | GENDER |      |
| $id        | xiandafu                         |      |        |      |
| $id2       | joelli                           |      |        |      |

## 编写场景测试

场景测试同输入是一样的规则，场景测试也可以再次定义一些场景测试的变量，这样在JUnit测试里，可以使用这些变量来测试。比如上图定义了一个变量test.password变量，JUnit可以取出这个变量，来更新用户密码，并做比较

场景里的每个表关心的数据可以用红色背景表示在列名上，这样XLSUnit仅仅比较红色即可，这有助于单元测试维护中几种注意力修改需要比较的关键数据

## include

includeSheet指令可以用来导入其他excel文件初始化数据。参数分别是excel文件，以及工作表名称

| ##includeSheet /common.xlsx userdata |      |      |      |      |
| ------------------------------------ | ---- | ---- | ---- | ---- |
|                                      |      |      |      |      |

可以将某些测试需要公共初始化的数据放到一个excel文件里，这样维护方便。

## fn系列函数

* fn.seq: 一个自增长的Long数据，用来模拟数据库序列或者其他Number数据
* fn.timestamp: 返回一个java的timestmap时间类型
* fn.sqlDate,返回一个java的 sqlDate
* fn.date 返回一个java.util.Date

可以自定义扩展，比如

~~~java
VariableTable vars = new VariableTable();
vars.getFns().put("myTest",new Function(){....});

~~~

# api



### VariableTable 变量表

xls里申明的变量或者操作数据库操作后的序列都放到此表里里，可以通过find方法，或者findSocpe获取变量

* vars.find("abc.age") 返回值
* vars.findInteger("abc.age") 返回整形
* vars.findScope("abc") 返回age,date name
* vars.find("$A$16"),返回输入表里的16行的A列数据。



### XLSParser 用于解析输入。

计算后，与输出比较，包括
* init 公共输入
* prepare(sheetName, vars),场景的数据准备 （这个不是必须调用的）
* test(sheetName, vars);将数据库结果与sheetName 描述的数据做对比



## 例子1

~~~java
@Test
public void testUser1() {
  //执行某个测试场景的初始化工作，初始化user表
  VariableTable vars = new VariableTable();
  userParser.init(vars);

  //开始测试，获取userId和password
  userParser.prepare("场景1", vars);	
  Integer id = (Integer) vars.find("id");
  String newPassword = vars.findString("test.password");
  //调用业务代码，修改用户密码
  userSerivce2.modifyUserInfo(id, newPassword);
  
  //比较数据库里的数据跟场景1的数据是否一致
  userParser.test("场景1", vars);

}
~~~



# 作者：

东方金科 李家智(闲大赋)