z3c.testsetup 0.8.4

注册 doctests

在此示例目录中，有一个简单的 doctest doctest01.txt（请忽略左侧的管道符号）

>>> print_file(os.path.join(cavepath, 'doctest01.txt'))
|  A doctest
|  =========
|
|  :doctest:
|
|  This is a simple doctest.
|
|    >>> 1+1
|    2
|

重要的是要注意：doctest 由一个特殊的标记标记，告诉测试设置机器该文件包含在测试运行期间应注册的 doctest 示例

:doctest:

没有这个标记，在测试期间不会注册测试文件！这是使用 z3c.testsetup 与‘正常’doctests之间的唯一区别。如果你想禁用测试，只需将 :doctest: 转换为 :nodoctest:（或其它），文件将被忽略。

运行测试

既然我们有一个可用的 doctest，我们可以编写一个测试设置例程，该例程收集所有测试，将它们注册，并将它们传递给测试运行器

>>> print(open(os.path.join(cavepath, 'simplesetup01.py')).read())
import z3c.testsetup
test_suite = z3c.testsetup.register_all_tests(
    'z3c.testsetup.tests.othercave',
    allow_teardown=True)

在简单情况下，我们只需要这些。我们使用 register_all_tests(<点分包名>) 来告诉设置机制在哪里查找测试文件。 allow_teardown 参数表示我们允许拆卸功能测试，这样它们就不必在独立的子进程中运行。请注意，子包中的文件也会被找到、注册并执行，前提是它们被适当地标记。

让我们启动测试运行器，看看它会给出什么

>>> import sys
>>> sys.argv = [sys.argv[0],]
>>> defaults = [
...     '--path', cavepath,
...     '--tests-pattern', '^simplesetup01$',
...     ]
>>> from z3c.testsetup import testrunner
>>> testrunner.run(defaults)
Running zope...testrunner.layer.UnitTests tests:
  Set up zope...testrunner.layer.UnitTests in 0.000 seconds.
    Custom setUp for  <DocTest doctest05.txt from ...doctest05.txt:0 (2 examples)>
    Custom tearDown for  <DocTest doctest05.txt from ...doctest05.txt:0 (2 examples)>
  Ran 4 tests with 0 failures and 0 errors in N.NNN seconds.
Running z3c...layer.DefaultZCMLLayer [...ftesting.zcml] tests:
  Tear down zope...testrunner.layer.UnitTests in N.NNN seconds.
  Set up z3c...layer.DefaultZCMLLayer [...ftesting.zcml] in N.NNN seconds.
  Ran 3 tests with 0 failures and 0 errors in N.NNN seconds.
Running z3c...layer.DefaultZCMLLayer [...ftesting2.zcml] tests:
  Tear down z3c...DefaultZCMLLayer [...ftesting.zcml] in N.NNN seconds.
  Set up z3c...layer.DefaultZCMLLayer [...ftesting2.zcml] in N.NNN seconds.
  Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
Running z3c.testsetup.tests.othercave.testing.FunctionalLayer1 tests:
  Tear down z3c...DefaultZCMLLayer [...ftesting2.zcml] in N.NNN seconds.
  Set up z3c....othercave.testing.FunctionalLayer1 in N.NNN seconds.
  Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
Running z3c.testsetup.tests.othercave.testing.UnitLayer2 tests:
  Tear down z3c...othercave.testing.FunctionalLayer1 in N.NNN seconds.
  Set up z3c.testsetup.tests.othercave.testing.UnitLayer1 in N.NNN seconds.
  Set up z3c.testsetup.tests.othercave.testing.UnitLayer2 in N.NNN seconds.
    Running testSetUp of UnitLayer1
    Running testSetUp of UnitLayer2
    Running testTearDown of UnitLayer2
    Running testTearDown of UnitLayer1
  Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
Tearing down left over layers:
  Tear down z3c...othercave.testing.UnitLayer2 in N.NNN seconds.
  Tear down z3c...othercave.testing.UnitLayer1 in N.NNN seconds.
Total: 10 tests, 0 failures, 0 errors in N.NNN seconds.
False

如我们所见，运行了常规的 unittests 以及功能测试。一些 unittests 使用了自己的层（UnitLayer1）。层在输出中显示。在这个例子中，功能测试使用不同的 ZCML 文件进行配置，这导致了单独的测试层。

在 Python 模块中查找 doctests

上面描述的 doctest 文件是一个纯 .txt 文件。默认情况下，z3c.testsetup 在具有文件扩展名 .txt、.rst 和 .py 的文件中查找 doctests。这意味着 Python 模块中的 doctests 也同样被找到，如下例所示

>>> print_file(os.path.join(cavepath, 'doctest08.py'))
|  """
|  Doctests in a Python module
|  ===========================
|
|  We can place doctests also in Python modules.
|
|  :doctest:
|
|  Here the Cave class is defined::
|
|    >>> from z3c.testsetup.tests.othercave.doctest08 import Cave
|    >>> Cave
|    <class 'z3c.testsetup...doctest08.Cave'>
|
|  """
|
|
|  class Cave(object):
|      """A Cave.
|
|      A cave has a number::
|
|        >>> hasattr(Cave, 'number')
|        True
|
|      """
|      number = None
|
|      def __init__(self, number):
|          """Create a Cave.
|
|          We have to give a number if we create a cave::
|
|            >>> c = Cave(12)
|            >>> c.number
|            12
|
|          """
|          self.number = number
|

这里我们将标记字符串 :doctest: 放入模块的文档字符串中。如果没有它，该模块就不会被认为是一个测试文件。

请注意，如果你想使用它们，必须从同一个文件中导入实体（类、函数等）。

注册常规 Python unittests

z3c.testsetup 还提供了（有限的）对常规 unittest 部署的支持，正如通常在 Python 中编写的。一个示例文件看起来像这样

>>> print_file(os.path.join(cavepath, 'pythontest1.py'))
|  """
|  Tests with real TestCase objects.
|
|  :unittest:
|
|  """
|  import unittest
|
|
|  class TestTest(unittest.TestCase):
|
|      def setUp(self):
|          pass
|
|      def testFoo(self):
|          self.assertEqual(2, 1+1)
|

该模块在其模块文档字符串中包含一个 :unittest: 标记，而不是上面其它示例中使用的 :doctest: 标记。这意味着该文件被注册为常规 unittest。（这也是以前使用的 :Test-Layer: python 标记的替代品。）

如果你使用 unittests 而不是 doctests，那么在设置和拆卸测试方面，你基本上是独立的。所有这些都应该由测试用例本身来完成。

使用 z3c.testsetup 的唯一优势是，当它们提供标记时，这些测试将被自动找到并运行。

设置自定义层： :layer:

从z3c.testsetup 0.3开始，对每个测试文件设置层提供了合理的支持。这样，您可以轻松创建仅在特定测试集之前/之后运行的设置函数。

总的来说，从现在起，建议使用层。

我们可以使用以下示例中的< span class="docutils literal">:layer:标记告诉z3c.testsetup使用特定的层（请参阅tests/othercave/doctest02.txt）

A doctests with layer
=====================
<BLANKLINE>
:doctest:
:layer: z3c.testsetup.tests.othercave.testing.UnitLayer2
<BLANKLINE>
  >>> 1+1
  2

这里也使用了:doctest:标记，因为没有它，文件就不会被检测为可注册的doctest文件（我们希望开发人员明确指出这一点）。

< span class="docutils literal">:layer: <DOTTED_NAME_OF_LAYER_DEF>标记告诉测试设置机制可以在哪里找到层定义。它以点名称表示法给出，指向您自己定义的层。

层定义看起来像什么？它被定义为常规Python代码

>>> print(open(os.path.join(cavepath, 'testing.py')).read())
import os
...
class UnitLayer1(object):
    """This represents a layer.
    A layer is a way to have common setup and teardown that happens
    once for a whole group of tests.
<BLANKLINE>
    It must be an object with a `setUp` and a `tearDown` method, which
    are run once before or after all the tests applied to a layer
    respectively.
<BLANKLINE>
    Optionally you can additionally define `testSetUp` and
    `testTearDown` methods, which are run before and after each single
    test.
<BLANKLINE>
    This class is not instantiated. Therefore we use classmethods.
    """
<BLANKLINE>
    @classmethod
    def setUp(self):
        """This gets run once for the whole test run, or at most once per
        TestSuite that depends on the layer.
        (The latter can happen if multiple suites depend on the layer
        and the testrunner decides to tear down the layer after first
        suite finishes.)
        """
<BLANKLINE>
    @classmethod
    def tearDown(self):
        """This gets run once for the whole test run, or at most
        once per TestSuite that depends on the layer,
        after all tests in the suite have finished.
        """
<BLANKLINE>
    @classmethod
    def testSetUp(self):
        """This method is run before each single test in the current
        layer. It is optional.
        """
        print("    Running testSetUp of UnitLayer1")
<BLANKLINE>
    @classmethod
    def testTearDown(self):
        """This method is run before each single test in the current
        layer. It is optional.
        """
        print("    Running testTearDown of UnitLayer1")
<BLANKLINE>
class UnitLayer2(UnitLayer1):
    """This Layer inherits ``UnitLayer1``.
<BLANKLINE>
    This way we define nested setups. During test runs the testrunner
    will first call the setup methods of ``UnitTest1`` and then those
    of this class. Handling of teardown-methods will happen the other
    way round.
    """
<BLANKLINE>
    @classmethod
    def setUp(self):
        pass
<BLANKLINE>
    @classmethod
    def testSetUp(self):
        print("    Running testSetUp of UnitLayer2")
<BLANKLINE>
    @classmethod
    def testTearDown(self):
        print("    Running testTearDown of UnitLayer2")

在层中，您可以执行所有必需的特殊操作，以正确运行特定测试组。我们这里的设置是特殊的，因为我们定义了一个嵌套的：UnitLayer2继承自UnitLayer1，因此在测试运行期间调用适当的设置和拆卸方法（请参阅上面的测试运行程序输出）。

有关测试层的信息，请参阅testrunner layers API文档。

指定 ZCML 文件： :zcml-layer:

在涉及到使用zope组件架构的集成测试时，我们需要指定一个ZCML文件来为我们配置测试环境。我们可以通过使用以下方法来实现：

:zcml-layer: <ZCML文件名>

标记。它期望一个ZCML文件名作为参数，并为我们设置一个ZCML分层测试套件。一个示例设置可能如下（参见 tests/othercave/doctest03.txt）

A doctest with a ZCML-layer
===========================

:doctest:
:zcml-layer: ftesting.zcml

  >>> 1+1
  2

在这里，我们指定本地文件 ftesting.zcml 应用作ZCML配置。正如我们在上面的测试运行器输出中看到的那样，此文件确实在测试运行期间被读取，并由一个名为 DefaultZCMLLayer 的ZCML层使用。实际上，这个层只是一个 zope.app.testing.functional.ZCMLLayer。

ZCML文件将在与doctest文件相同的目录中查找。（顺便说一句，您可以使用相对路径，如 ../ftesting.zcml）。

当使用 :zcml-layer: 标记时，相关的测试将通过 zope.app.testing 的特殊方法和函数来设置。这样，您可以获得“功能”或“集成”测试：一开始设置一个空的ZODB db，将 getRootFolder、sync 和其他函数拉入测试命名空间，还有更多。

如果您想使用普通的设置，则使用自己的层定义 :layer: 并删除 :zcml-layer: 标记。

设置功能 ZCML 层： :functional-zcml-layer:

有时我们希望使用 zope.app.testing.functional 中的 FunctionalDocFileSuite 函数（其他测试使用 doctest.DocFileSuite 设置）来注册测试。此函数将更多函数拉入 globs，如 http（一个 HTTPCaller 实例），将您的 setUp 和 tearDown 方法包装到ZODB设置中，还有更多。请参阅http://svn.zope.org/zope.app.testing/trunk/src/zope/app/testing/functional.py?view=auto中的定义。

此设置还需要一个ZCML配置文件，可以通过以下方式指定：

:functional-zcml-layer: <ZCML-file-name>

如果以这种方式在测试文件中指定了功能ZCML层，则它将覆盖任何简单的 :zcml-layer: 或 :layer: 定义。

一个示例设置可能如下（参见 tests/othercave/doctest04.txt）

>>> print_file(os.path.join(cavepath, 'doctest04.txt'))
|  A functional doctest with ZCML-layer
|  ====================================
|
|  :doctest:
|  :functional-zcml-layer: ftesting.zcml
|
|  We didn't define a real environment in ftesting.zcml, but in
|  functional tests certain often needed functions should be available
|  automatically::
|
|    >>> getRootFolder()
|    <zope...folder.Folder object at 0x...>
|

在 zope 和 folder 之间的占位符被使用，因为Folder类的位置最近有所改变。这样，我们可以同时覆盖旧包和最新包的设置。

指定测试设置/拆卸方法： :setup: 和 :teardown:

我们可以在doctest文件中的示例中指定 setUp(test) 和 tearDown(test) 方法，这些方法将为整个doctest文件执行一次。这可以通过以下方式完成：

:setup: <dotted.name.of.callable>
:teardown: <dotted.name.of.callable>

由点名称表示的调用函数必须接受一个 test 参数，它将是当前doctest文件中所有示例的整个测试套件。setup/teardown可以用于设置（并删除）临时目录，对邮件发送器进行monkeypatch等。

一个示例可以在 doctest05.txt 中找到

>>> print_file(os.path.join(cavepath, 'doctest05.txt'))
|  A doctest with custom setup/teardown functions
|  ==============================================
|
|  :doctest:
|  :setup: z3c.testsetup.tests.othercave.testing.setUp
|  :teardown: z3c.testsetup.tests.othercave.testing.tearDown
|
|    >>> 1+1
|    2
|
|  We make use of a function registered during custom setup::
|
|    >>> myfunc(2)
|    4
|

示例中指定的setup/teardown函数看起来像这样

>>> print(open(os.path.join(cavepath, 'testing.py'), 'r').read())
import os
...
def setUp(test):
    print("    Custom setUp for %s" % test)
    # We register a function that will be available during tests.
     test.globs['myfunc'] = lambda x: 2*x
<BLANKLINE>
def tearDown(test):
    print("    Custom tearDown for %s" % test)
    del test.globs['myfunc'] # unregister function
...

正如我们所看到的，有一个函数 myfunc 被拉入doctest的命名空间。然而，我们也可以在这里做任意其他的事情，设置一个关系型测试数据库或 whatever。

废弃的 :Test-Layer: 标记

如果您仍然使用 :Test-Layer: 标记您的测试文件，请按照以下方式更新您的测试文件

• :Test-Layer: unit

  改为：:doctest:

• :Test-Layer: python

  改为：:unittest:

• :Test-Layer: functional

  改为：:functional-zcml-layer: <ZCML-FILE>

  必须显式给出 ZCML 文件。

如果您使用了传递给 register_all_tests 的自定义设置，请考虑使用 :setup: 和 :teardown: 在适当的 doctest 文件中声明这些设置/拆卸函数。

当使用新的层标记 :layer:、:zcml-layer: 和 functional-zcml-layer: 时，您可能会得到更好的结构化测试套件。

废弃的 register_all_tests() 参数

以下 register_all_tests-参数从 z3c.testsetup 0.3 开始已弃用

• filter_func

  和相关 (ufilter_func、pfilter_func 等)

• 所有测试类型特定的参数

  对测试文件特定参数（uextensions、fextensions 等）的支持正在减少，并且其使用已被弃用。

错误修复

• 检查器现在也应用于非功能性的doctests。感谢Jonathan Ballet提供的补丁。

• 正常的UnitTest层现在被正确注册。

• :layer:现在可以检测功能性的ZCML层。如果定义的层是从zope.testing.functional.ZCMLLayer派生的，那么测试将使用与:functional-zcml-layer:相同的测试用例类型来设置。

• 重新排序并整理了文档。

功能变更

• 默认情况下，功能层测试现在使用ZCMLLayer的allow_teardown=True选项。这可以防止zcml层在一个子进程中运行，这会干扰分析工具，从而影响代码覆盖率。只有在像在代码中事后向类添加接口这样的情况下，才需要在子进程中运行它。您可以在register_all_tests()调用中通过设置allow_teardown=False来覆盖它。

错误修复

• 使z3c.testsetup自检与zope.testing >= 3.7.3兼容。感谢Jonathan Ballet指出该问题。

• 默认情况下忽略*nix隐藏的测试文件（即以点开始的文件名）。感谢Jonathan Ballet提供的补丁。

• 通过默认层注册的ZCML文件现在彼此分离，即使它们拥有相同的文件名。因此，您现在可以在一个子包中注册一个包含ftesting.zcml的默认层，同时在一个包中拥有另一个ftesting.zcml。之前没有正确处理这个问题。非常感谢Jonathan Ballet提供的补丁。

功能变更

• 添加了z3c.testsetup.testrunner，它为zope.testing.testrunner的 run()和run_internal()函数提供了包装器。使用它，可以确保在测试运行期间运行测试运行器将正常工作，无论测试运行期间使用的是哪个版本的zope.testing。

错误修复

• 更新了doctest示例，以反映新的zope.testing行为。

• z3c.testsetup实际上不再需要zope.app.testing。如果您在不使用此包的环境中使用它，那么您将无法注册功能测试，这是在从z3c.testsetup加载register_all_tests时确定的。

• 在扫描测试时忽略损坏的模块。

• 如果模块的源代码不提供合适的标记字符串，则不再加载这些模块。为了实现这一点，默认检查器方法isTestModule现在期望一个martian.scan.ModuleInfo作为参数，而不是一个真实的模块。可以使用martian.scan包中的module_info_from_dotted_name和module_info_from_package轻松创建模块信息。

功能变更

• 新的一组测试文件标记

  • :doctest

    将测试文件标记为doctest。

  • :unittest

    将测试文件标记为常规unittest。

  • :layer: dotted.name.to.layer.def

    将给定的层定义应用于doctest文件中的测试。

  • :zcml-layer: filename.zcml

    使用给定的文件名设置ZCML层，并将其应用于doctest文件中的doctests。

  • :functional-zcml-layer: filename.zcml

    使用给定的文件名设置ZCML层，并将其应用于doctest文件中的doctests。此外，测试还将被设置为功能doctests。

  • :setup: dotted.name.to.setup.function

    将指定的点名称表示的setUp函数应用于doctest文件中的测试。

  • ：拆卸：dotted.name.to.teardown.function

    将指定的拆卸函数应用于doctests文件中的测试。

  有关使用这些新指令的示例，请参阅tests/othercave和README.txt。

  旧的:test-layer:标记仍然受支持，但现在已弃用，将在z3c.testsetup的0.5版本中消失。

功能变更

• 如果存在，将包根目录中的ftesting.zcml视为功能doctests的默认层。

错误修复