Using This Package

intercom_test provides InterfaceCaseProvider to iterate over test cases defined in YAML files. With the additional use of a case_augmenter – either an HTTPCaseAugmenter, a RPCCaseAugmenter, or your own class derived from CaseAugmenter – the InterfaceCaseProvider can add more data from a different directory to any test case; this supports decoupling a service provider’s implementation details necessary to passing the given test case from the request and response information needed by both the consumer and the provider.

intercom_test, when installed with the [cli] extra, also provides a command line tool called icy-test. This tool makes the core functionality of intercom_test available to programs written in languages other than Python.

What It Looks Like In Practice

_images/example_project_structure.png

Example directory tree for using intercom_test

The intercom_test package does not make many requirements of the directory structure for the project using it, but here is one example of how a project could be structured to use intercom_test.

This package has no direct concern with the src folder. Within the test folder, this example project has split the data managed by intercom_test into component_interfaces and component_test_env. The structure, relationship, and usage of these two folders are described below.

In this example, the component_interfaces contain both a main test case file, ($PROJECT/test/component_interfaces/service.yml) and also an extension file ($PROJECT/test/component_interfaces/service/ext-1.yml), which will be combined into a single set of test cases by intercom_test. Any additional .yml files added to the $PROJECT/test/component_interfaces/service folder will also be read as additional test cases for service. Typically, the component_interfaces folder would be shared with the projects intending to consume this service via some version control mechanism like a Git submodule or a Subversion externals definition. When constructing an InterfaceCaseProvider with the example_project directory as the current directory, the first argument should be "test/component_interfaces" and the second argument "service" (indicating both the service.yml file and all files matching service/*.yml).

Additionally, the component_test_env subfolder contains information necessary for testing the service-provider, but which doesn’t affect the component interface – database fixtures, data for mocking external services, etc. Within this folder, the augmentation data for the “service” is the set of YAML (.yml) files located in the service folder; it is important to note that the augmentation data will come from all files within the given folder, so having a separate folder for each interface is probably wise. The path to pass when constructing one of the standard CaseAugmenter subclasses would therefore be "test/component_test_env/service". Since this information is only important for testing the provider and is tightly coupled to the provider implementation, the entire component_test_env folder should probably be a part of the service provider’s source code repository and not shared with service consumers. This example only contains one such file, named feature-1.yml, but as many augmentation files as desired can be created, though there is a restriction on augmenting a single test case in multiple separate files.

So, assuming this project represents some kind of HTTP API, the most logical way to create the InterfaceCaseProvider for this directory structure is:

from intercom_test import InterfaceCaseProvider, HTTPCaseAugmenter

...

def get_interface_case_provider():
    return InterfaceCaseProvider(
        "test/component_interfaces", "service",
        case_augmenter=HTTPCaseAugmenter("test/component_test_env/service")
    )

...

Indices and tables