PostgreSQL教程（三十六）：服务器管理（十八）之回归测试

回归测试是PostgreSQL中对于 SQL 实现的一组综合测试集。它们测试标准 SQL 操作以及PostgreSQL的扩展能力。

一、运行测试

回归测试可以在一个已经安装并运行的服务器上运行，或者在编译树中的一个临时安装上运行。此外，还有运行该测试的“并行”和“顺序”模式。顺序方法单独运行每一个测试脚本，而并行方法则开启多个服务器进程来并行地运行多组测试。并行测试能够发现进程间通信和锁定是否工作正确。

1.1. 在一个临时安装上运行测试

要在编译之后且在安装之前运行并行回归测试，可在顶层目录中键入：

make check

（或者你可以切换到src/test/regress并且在那里运行该命令）。最后你应该看到这样的信息：

=======================
 All 115 tests passed.
=======================

或者关于哪些测试失败的提示。见下面的第二节来确定一个“失败”是否表示一个严重的问题。

因为这种测试方法运行一个临时服务器，如果你作为根用户进行了编译，它将无法工作，因为服务器无法用 root 启动。我们推荐的过程是不要作为 root 编译，或者在完成安装后执行测试。

如果你已经配置PostgreSQL安装到一个已经存在有旧的PostgreSQL安装的位置，并且你在安装新版本前执行了make check，你可能会发现测试会因为新程序尝试使用已经安装的共享库而失败（典型特征是抱怨未定义的符号）。如果你希望在覆盖旧安装之前运行测试，你将需要使用configure --disable-rpath编译。但是我们不推荐为最终安装使用这个选项。

并行回归测试会在你的用户 ID 下启动相当多的进程。当前，最大并发量是二十个并行测试脚本，这意味着四十个进程：对每一个测试脚本有一个服务器进程和一个psql进程。因此如果你的系统对每个用户的进程数有强制限制，确保这个限制至少是五十，否则你将在并行测试中失败。如果你没有权利提升该限制，你可以通过设置MAX_CONNECTIONS参数来降低并发度。例如：

make MAX_CONNECTIONS=10 check

会并发运行不超过十个测试。

1.2. 在一个现有安装上运行测试

要在安装后运行测试（见教程十九），初始化一个数据区域并且按照教程二十一所解释的启动服务器，然后输入：

make installcheck

或者进行一次并行测试：

make installcheck-parallel

该测试将期望联系在本地主机和默认端口号上的服务器（除非通过PGHOST和PGPORT环境变量覆盖）。该测试将在一个名为regression的数据库中运行，任何以该名称存在的数据库将被删除。

该测试还将短暂地创建一些集簇范围内的对象，例如角色和表空间。这些对象的名称都会以regress_开始。在实际具有以这种方式命名对象的安装中使用installcheck模式时要格外小心。

1.3. 附加测试套件

make check和make installcheck命令只运行“核心的”回归测试，这只测试PostgreSQL服务器的内建功能。源代码发布也包含额外的测试套件，它们中的大部分用于测试附加功能，例如可选的过程语言。

要运行将被编译模块的所有测试套件（包括核心测试），在编译树的顶端输入这些命令之一：

make check-world
make installcheck-world

这些命令分别在临时服务器或已经安装好的服务器上运行测试（与之前介绍的make check和make installcheck类似）。其他的考虑与之前为每种方法解释的相同。注意make check-world为每一个受测模块建立一个独立的临时安装树，因此它比起make installcheck-world需要更多的时间和磁盘空间。

你也可以通过在编译树适当的子目录中输入make check或make installcheck来运行个体的测试套件。记住make installcheck假设你已经安装了相关模块，而不仅仅是核心服务器。

可以以这种方法调用的额外测试包括：

• 可选过程语言的回归测试（除PL/pgSQL之外，它将被核心测试测试）。这些位于src/pl之下。

• contrib模块的回归测试，位于contrib。不是所有的contrib模块都有测试。

• ECPG 接口库的回归测试，位于src/interfaces/ecpg/test。

• 并发会话行为的压力测试，位于src/test/isolation。

• 客户端的测试程序在src/bin下。另见 第四节。

在使用installcheck模式时，这些测试将毁掉任何现有的名为pl_regression、contrib_regression、isolation_regression、ecpg1_regression或者ecpg2_regression的数据库，以及regression。

只有在PostgreSQL被使用选项--enable-tap-tests配置时，基于TAP的测试才能被运行。推荐在开发时使用这种方式，但如果没有合适的Perl安装可用也可以忽略。

一些测试套件默认不会被运行，因为它们在多用户系统上运行不安全或者它们需要特殊的软件。可以通过设置make或环境变量为空格分隔的列表来决定额外运行哪些测试套件，例如：

make check-world PG_TEST_EXTRA='kerberos ldap ssl'

当前支持下列值：

kerberos

        运行src/test/kerberos下的测试套件。这要求一个MIT Kerberos安装并且打开TCP/IP监听端口。

ldap

        运行src/test/ldap下的测试套件。这要求一个OpenLDAP安装并且打开TCP/IP监听端口。

ssl

        运行src/test/ssl下的测试套件。这会打开TCP/IP监听端口。

即便在PG_TEST_EXTRA中提到了当前编译配置不支持的特性，针对它们的测试也不会被运行。

1.4. 区域和编码

默认情况下，测试使用的临时安装将使用在当前环境中定义的区域和由initdb决定的相应数据库编码。通过设置适当的环境变量来测试不同的区域是有用的，例如：

make check LANG=C
make check LC_COLLATE=en_US.utf8 LC_CTYPE=fr_CA.utf8

由于实现的原因，为此目的设置LC_ALL不能工作，所有其他区域相关的环境变量都可以工作。

在对一个现有安装测试时，区域由现有数据库集簇决定并且不能为测试而独立设置。

你也可以通过设置变量ENCODING来显式地选择数据库编码，例如：

make check LANG=C ENCODING=EUC_JP

这样设置数据库编码通常只对区域为 C 有意义；否则编码将自动从区域选择，并且指定一个不匹配区域的编码将会导致错误。

不管测试是针对临时安装还是已有安装，数据库编码都可以被设置，然而在后一种情况中它必须与安装的区域相兼容。

1.5. 额外测试

核心回归测试套件包含一些默认情况下不被运行的测试文件，因为它们可能平台相关的或者需要很长时间来运行。你可以通过设置变量EXTRA_TESTS来运行这些或者其他额外测试文件。例如，要运行numeric_big测试：

make check EXTRA_TESTS=numeric_big

要运行排序规则测试：

make check EXTRA_TESTS='collate.icu.utf8 collate.linux.utf8' LANG=en_US.utf8

collate.linux.utf8测试只在 Linux/glibc 平台上能够工作。只有在编译了ICU支持时，collate.icu.utf8测试才能工作。两种测试只有在使用 UTF-8 编码的数据库中才能成功运行。

1.6. 测试热备

源代码发布中还包含有用于热备的静态行为的回归测试。这些测试需要一个运行着的主服务器和一个运行着的后备服务器，并且后备服务器正从主服务器接受新的 WAL 改变（使用基于文件的日志传送或流复制）。那些服务器不是自动创建的，这里也没有关于建立复制的文档。请查阅本文档中的相关章节。

要运行热备测试，首先在主服务器上创建一个名为regression的数据库：

psql -h primary -c "CREATE DATABASE regression"

接下来，在主服务器上的 regression 数据库中运行准备脚本src/test/regress/sql/hs_primary_setup.sql，例如：

psql -h primary -f src/test/regress/sql/hs_primary_setup.sql regression

允许这些改变传播到后备服务器。

为受测后备服务器安排默认数据库连接（例如通过设置PGHOST和PGPORT环境变量）。最后，在 regression 目录中运行make standbycheck：

cd src/test/regress
make standbycheck

在主服务器上也可以使用src/test/regress/sql/hs_primary_extremes.sql脚本生成某些极限行为来允许测试后备服务器的行为。

二、测试评估

一些正确安装的并且全功能的PostgreSQL安装可能会在这些回归测试中的某些上“失败”，其原因是平台相关的因素，例如可变浮点表示和 message wording。这些测试目前采用diff命令来比较测试输出和在参考系统上产生的输出，这样测试的结果对小的系统差异也很敏感。当一个测试被报告为“失败”时，请总是检查实际结果和期望结果之间的差异，你可能会发现该差异其实并不明显。不管怎样，我们将努力维护在所有被支持平台上的准确的参考文件，以期待所有的测试都能通过。

回归测试的实际输出在src/test/regress/results目录中的文件内。测试脚本会使用diff来把每一个输出文件与存储在src/test/regress/expected目录中的参考输出进行比较。任何差异都被保存在src/test/regress/regression.diffs中便于你的观察（当运行一个除核心测试之外的测试套件时，这些文件当然会出现在相关子目录中，而不是src/test/regress）。

如果你不喜欢被默认使用的diff选项，请设置环境变量PG_REGRESS_DIFF_OPTS，例如PG_REGRESS_DIFF_OPTS='-u'（或者如果你愿意，你可以自己运行diff）。

如果由于某种原因一个特定的平台对一个给定测试产生了“失败”，而对输出的检查却说明该结果是合法的，你可以增加一个新的比较文件来让失败报告在未来的测试运行中保持沉默。详见第三节。

2.1. 错误消息差异

某些回归测试涉及到故意的非法输入值。错误消息可能来自PostgreSQL代码或主机平台系统例程。在后一种情况中，消息会随着平台而变化，但是会反映相似的信息。这些消息中的差异将导致一次“失败的”回归测试，这可以通过检查来确认。

2.2. 区域差异

如果你在一台使用除 C 之外的排序规则顺序区域初始化的服务器上运行测试，那么可能会出现由于排序顺序和后续失败产生的差异。回归测试套件被设置为可以处理这种问题，方法是提供替代的结果文件来处理大量的区域。

要在使用临时安装方法时在一种不同的区域中运行测试，可在make命令行上传递适当的区域相关的环境变量，例如：

make check LANG=de_DE.utf8

（回归测试驱动器会取消LC_ALL设置，因此使用这个变量选择区域是不起作用的）。要不使用区域，要么取消所有区域相关的环境变量设置（或把它们设置为C），要么使用下列特殊调用：

make check NO_LOCALE=1

当对一个现有安装运行测试时，区域设置由现有安装决定。要改变它，通过向initdb传递合适的选项来使用不同的区域初始化数据库集簇。

通常，我们建议对将要在生产环境中使用的区域设置运行回归测试，因为这样可以测试即将真正被用在生产环境中的与区域和编码相关的代码。根据 操作系统环境，你可能会得到失败，但是那样你将至少知道在真实应用运行时会得到什么样的与区域相关的行为。

2.3. 日期和时间差异

大部分的日期和时间结果依赖于时区环境。参考文件是用时区PST8PDT（伯克利，加利福利亚）生成的，并且如果测试不是运行在该时区设置中显然会出现失败。回归测试驱动器会设置环境变量PGTZ为 PST8PDT，这通常能保证正确的结果。

2.4. 浮点差异

某些测试涉及到从表列中计算 64 位浮点数（双精度）。我们已经发现了涉及到双精度列的数学函数的结果中的差异。float8和geometry测试容易在不同平台之间产生小的差异，甚至对不同的编译器优化设置也可能产生差异。这些差异通常位于小数点右边的 10 个位置，决定这些差异的实际意义需要人类眼球比较。

某些系统显示负零为-0，而其他的只显示0。

某些系统标志来自pow()和exp()的错误的机制不同于当前PostgreSQL代码所期望的机制。

2.5. 行序差异

你可能看到这样一些差异：一组相同的行在输出中的顺序与参考文件中的顺序不同。严格来说，在大部分情况下这不是缺陷。大部分回归测试脚本没有为每一个单独的SELECT使用一个ORDER BY，并且因此它们的结果行顺序根据 SQL 规范是非良定义的。实际上，因为我们考虑的是由相同的软件在相同的数据上执行相同的查询，我们通常会在所有平台上得到相同的结果顺序，所以缺少ORDER BY不是一个问题。但是，某些查询确实会在不同平台上产生不同的顺序。当对一个已经安装的服务器运行测试时，顺序差异可能由非 C 区域设置或非默认参数设置导致，例如work_mem的自定义值或规划器代价参数。

因此，如果你看到一个顺序差异，没有什么可担心的，除非结果被未被的查询确实有一个ORDER BY。但是，不管怎样请报告它，这样我们可以为特定的查询加上一个ORDER BY来在未来的发布中消除虚假的“失败”。

你可能好奇为什么我们不对所有回归测试查询进行显式排序来一次性解决这个问题。其原因是那可能会降低回归测试的有用性，因为它们已经倾向于测试产生有序结果的查询计划类型而排除了那些无法产生有序结果的计划类型。

2.6. 栈深度不足

如果错误测试导致了在select infinite_recurse()命令上的一次服务器崩溃，它意味着平台对进程栈尺寸的限制低于max_stack_depth参数所指定的值。这可以通过在一个更高的栈尺寸限制（对max_stack_depth的默认值，我们推荐 4 MB）下运行该服务器来修复。如果你不能这样做，一种可替代的方案是减小max_stack_depth的值。

在支持getrlimit()的平台上，服务器应该自动选择一个max_stack_depth的安全值。所以除非你已经手工覆盖了该设置，这类失败就是一个可报告的缺陷。

2.7. “随机”测试

随机测试脚本用来产生随机结果。在非常少见的情况下，这会导致回归测试失败。输入：

diff results/random.out expected/random.out

应当产生一行或少数几行差异。你不需要担心，除非随机测试重复地失败。

2.8. 配置参数

当对一个现有安装运行测试时，某些非默认参数设置可能导致测试失败。例如，改变enable_seqscan或enable_indexscan等参数可能导致计划改变，然后影响使用EXPLAIN的测试的结果。

三、变体比较文件

因为某些测试生来就会产生依赖环境的结果，我们提供了方法来指定替代的“预期”结果文件。每一个回归测试可以有多个比较文件来展示在不同平台上的可能结果。有两种独立的机制来决定为每一个测试使用哪个比较文件。

第一种机制允许为指定平台选择比较文件。这是一个映射文件src/test/regress/resultmap，它定义了为每一个平台使用哪个比较文件。要为一个特定平台消除虚假的测试“失败”，你可以首先选择或创建一个变体结果文件，然后在resultmap文件中增加一行。

在该映射文件中的每一行的形式为：

testname:output:platformpattern=comparisonfilename

测试名只是该特定回归测试模块的名称。输出值指定要检查哪个输出文件。对于标准回归测试，这总是out。该值对应于输出文件的文件扩展。平台模式是一个 Unix 工具expr风格的模式（即在开头带有一个隐式^锚的正则表达式）。它被与config.guess打印出的平台名称进行匹配。匹配文件名称是替补的结果比较文件的基础名。

例如：某些系统会把非常小的浮点值解释为零，而不是报告一个下溢错误。这在float8回归测试中会导致一些差异。因此，我们提供一个变体比较文件float8-small-is-zero.out，其中包括了在这些系统上的期望结果。要在OpenBSD平台上屏蔽这种虚假的“失败”消息，resultmap包括：

float8:out:i.86-.*-openbsd=float8-small-is-zero.out

这将在任何config.guess输出匹配i.86-.*-openbsd的机器上触发。resultmap中的其他行为其他平台选择变体比较文件。

第二种变体比较文件的选择机制更加自动：它简单地在多个提供的比较文件中采用“最佳匹配”。回归测试驱动器脚本对一个测试考虑两种标准比较文件，testname.out以及名为testname_digit.out的变体文件（其中digit是任何单一数字0-9）。如果任一这种文件是一个完全匹配，测试被认为是通过的。否则，产生最短区别的文件被用来创建失败报告（如果resultmap包括特定测试的一个项，那么基础testname是resultmap中给定的替补名称）。

例如，对于char测试，比较文件char.out包含在C和POSIX区域中期望的结果，而文件char_1.out包含在其他很多区域中的排序结果。

最佳匹配机制被设计为与区域依赖的结果协同工作，但是它可以被用在任何测试结果无法只从平台名很容易地预测的情况中。这种机制的一个限制是测试驱动器不能说出哪个变体对当前环境是真正“正确的”，它将只是选择看起来工作得最好的变体。因此对你认为在所有上下文中具有同等合法性的变体结果使用这种机制才是最安全的。

四、TAP 测试

很多测试，特别是src/bin下面的客户端程序测试使用 Perl 的 TAP 工具并且用Perl测试程序prove运行。你可以通过 设置make变量PROVE_FLAGS 向prove传递命令行选项，例如：

make -C src/bin check PROVE_FLAGS='--timer'

详见prove的手册页。

make变量PROVE_TESTS可被用来定义一个空格分隔的列表，其中是调用prove来运行的指定测试子集的路径，这些测试子集将取代默认的t/*.pl，并且这些路径是相对于Makefile的。例如：

make check PROVE_TESTS='t/001_test1.pl t/003_test3.pl'

TAP测试需要 Perl 模块IPC::Run。 这个模块可以从 CPAN 或者一个操作系统包得到。

五、测试覆盖检查

PostgreSQL 源代码可以使用覆盖测试指令编译，因此可以检查哪些部分的代码被回归测试或任何其他测试套件所覆盖。当前使用 GCC 编译时支持该特性，并且需要gcov和lcov程序。

一个典型的工作流程看起来是：

./configure --enable-coverage ... OTHER OPTIONS ...
make
make check # 或其他测试套件
make coverage-html

然后将你的 HTML 浏览器指向coverage/index.html。make命令在子目录中也能工作。

如果没有lcov或者更喜欢文本输出而不是HTML报告，还可以运行

make coverage

来取代make coverage-html，它将为每个与测试相关的源文件产生.gcov输出文件（make coverage和make coverage-html将覆盖彼此的文件，所以把它们混合在一起可能会导致混乱）。

要在多次测试运行之间重置执行计数，运行：

make coverage-clean