DolphinDB 单元测试教程

在 DolphinDB 中，使用 @testing:case="testName" 标签为脚本声明测试用例。测试用例的命名应与测试内容相关，以便于理解和维护。每个测试用例声明应具有唯一名称。如果存在重复的测试用例名，在执行单元测试时，若断言未通过，将无法确定是哪个测试用例失败。为了便于区分，不同测试用例之间应有空行隔开。以下是两个不同测试用例的声明示例：

@testing:case="function_sum_int"
re = sum(1 NULL 2)
assert 1, eqObj(re,3)
@testing:case="function_sum_overflow"
assert 1, sum(int(2147483647..2147483649)) == 0

测试用例声明还可以包含可选属性。例如，若测试某种语法错误而预期抛出异常的场景，需要加上 syntaxError=1 属性:

@testing:case="parse_constant_vector_void_type", syntaxError=1
{,}

若测试非语法层面的预期异常场景，例如函数参数输入错误，需要加上 exception=1 的属性：

@testing:case="sum_not_support_matrix_zero_column", exception=1
m = matrix(`INT, 10, 0);
sum(m)

默认情况下，即没有指定任何属性时，表示该测试用例是一个正向的测试用例，预期不会抛出异常。

DolphinDB 测试框架中的断言方法与其他语言提供的断言方法有所不同。例如 Python 语言的 unittest 测试框架，提供了多种不同的断言方法来比较不同的数据类型结果是否符合预期：assertEqual(a, b) 验证 a 和 b 是否相等，assertNotEqual(a, b) 验证 a 和 b 是否不相等，assertTrue(x) 验证 x 是否为 True 等。而在 DolphinDB 中的断言统一使用 assert 语句，使用语法如下：

assert <expr>

或

assert <subCase>, <expr>

其中 <subCase> 是一个字符串，即使未使用引号，也会被解析为字符串； expr 是一个布尔值或返回布尔值的表达式。同一个测试用例中，如果包含多个断言，每个 <subCase> 应保持唯一性。否则，在执行单元测试时 ，如果某个测试用例中有断言失败，无法根据测试结果定位到具体是哪个断言失败。

从使用语法中可以看出，无论要判断何种情况下，实际输出结果是否符合预期，只需要确保 <expr> 最终返回的结果是布尔值即可。返回 true 表示断言通过；返回 false 表示断言失败，测试用例返回的实际结果与预期不一致：

@testing:case="function_sum_int"
re = sum(1 2)
assert 1, eqObj(re,3) //pass
assert 2, eqObj(re,0) //fail

注意如果 <expr> 返回的结果是布尔向量，则向量内的元素都为 true，才算断言通过：

@testing:case="function_cumsum_int"
re = cumsum(1 2 3)
assert 1, eqObj(re,[1,3,6]) //pass
assert 2, eqObj(re,[1,2,6]) //fail

在一般测试场景中， <expr> 是一个表达式。在DolphinDB 中，支持表达式的数据类型主要包括：标量、数据对、向量、矩阵和集合。如果需要判断两个表或者字典是否相等，则需要采用绕行的方法。在第1.3节中，将介绍在典型的测试场景下，如何有效的将测试用例返回的各种形式的测试结果和预期结果进行比较。

其他语言的测试框架中，通常在异常用例处理中可以测试是否抛出了指定异常类型，例如 Python 的 pytest框架使用 pytest.raises() 来断言某个函数或方法是否会抛出特定类型的异常:

import pytest
def divide(a, b):
    if b == 0:
        raise ZeroDivisionError("division by zero")
    return a / b
def test_divide_by_zero():
    with pytest.raises(ZeroDivisionError):
        divide(10, 0)
def test_divide_by_non_zero():
    with pytest.raises(TypeError):
        divide(10, "hello")

在第一个测试函数 test_divide_by_zero 中，期望 divide 函数在除以零时抛出 ZeroDivisionError 异常，因此使用 pytest.raises 来检查这个异常是否被正确抛出。在第二个测试函数 test_divide_by_non_zero 中，期望在 divide 函数传入一个非零整数和一个字符串作为除数时会抛出 TypeError 异常。同样使用 pytest.raises 来检查这个异常是否被抛出。

在 DolphinDB 中，判断非语法层面的异常用例时，只支持 exception=1 属性。如果需要进一步判断异常的类型，应使用 try-catch 语句捕获异常信息，并通过 assert 断言异常类型和信息是否符合预期。此时，用例声明中不需要添加 exception=1 属性，因为该用例的异常已被捕获：

@testing:case="sum_not_support_matrix_zero_column"
try{
	m = matrix(`INT, 10, 0);
	sum(m)
}catch(ex){
	assert 1,eqObj(ex[0],"SYSTEM_Runtime")//断言异常类型
	assert 2,eqObj(ex[1],"The column number of matrix must be greater than 0.")//断言异常信息
}

在比较测试用例返回的实际结果与预期是否一致时，通常存在两种场景。第一种场景要求实际测试结果的类型和值都与预期结果一致；第二种场景则只需确保测试结果的值与预期值一致，不考虑类型。在第一种场景下，我们使用 eqObj 函数进行比较，该函数检查两个对象的类型和值是否相同。仅当类型和值都相同时，此函数才返回 true；如果值相同但类型不同，则函数返回 false:

eqObj(1.0,1)
//output:false

在测试用例中体现如下：

@testing:case="function_sum_double"
re = sum(1.0 2.0)
assert 1,eqObj(re,3.0)
//pass
assert 2,eqObj(re,3)
//fail

对与第二种场景，我们使用 eq(X, Y) 或 X==Y 进行比较，因为对与 eq(X, Y) 或 X==Y ，当 X 和 Y 的类型不同，但值相同时，返回的结果仍为 true:

eq(1.0,1)
//output:true
1.0==1
//output:true

在测试用例中体现如下：

@testing:case="function_sum_double"
re = sum(1.0 2.0)
assert 1,re==3.0
//pass
assert 2,re==3
//pass

如果比较的两个对象是浮点数，并且计算得到的小数位很长，一般只需要保证结果在一定的误差范围内即可，这种情况我们也推荐使用 eqObj 函数来比较，因为 eqObj 比较时可以指定 precision 参数，指定该参数时，该函数返回的结果，等价于 abs(obj1-obj2)<=pow(10,-precision) 返回的结果来判断 obj1 和 obj2 的值是否相等。例如：

eqObj(1.00115, 1.00135, 4)
//output:false
eqObj(1.00115, 1.00125, 4)
//output:true

如果测试用例中，需要验证一个数据表的结果是否符合预期，无法直接使用 eq（==） 或者 eqObj 函数，因为这两个比较方法不支持表对象，此时，我们需要通过 values 函数将表格的列转换为一个 tuple，然后使用在高阶函数 each 内使用 eq（==） 或 eqObj 来逐列对比两个表的值，返回结果是与列数相等的布尔向量，这种比较方法可以直观的看出两个表的哪一列不相同：

@testing:case="function_cumsum_table"
re = cumsum(table(1 2 3 as x, 4 5 6 as y))
ex = table(1 2 6 as x,4 9 15 as y)
assert 1,each(eqObj, t1.values(), t2.values())