intercom_test.framework module

class intercom_test.framework.CaseAugmenter(augmentation_data_dir)

Bases: object

Base class of case augmentation data managers

This class uses and manages files in a case augmentation directory. The data files are intended to either end in ‘.yml’ or ‘.update.yml’. The version control system should, typically, be set up to ignore files with the ‘.update.yml’ extension. These two kinds of files have a different “data shape”.

Update files (ending in ‘.update.yml’) are convenient for manual editing because they look like the test case file from which the case came, but with additional entries in the case data dict. The problems with long term use of this file format are A) it is inefficient for correlation to test cases, and B) it duplicates data from the test case, possibly leading to confusion when modifying the .update.yml file does not change the test case.

Compact data files (other files ending in ‘.yml’) typically are generated through this package. The format is difficult to manually correlate with the test file, but does not duplicate all of the test case data as does the update file data format. Instead, the relevant keys of the test case are hashed and the hash value is used to index the additional augmentation value entries.

It is an error for a test case to have multiple augmentations defined within .yml files (excluding .update.yml files), whether in the same or different files. It is also an error for multiple files with the .update.yml extension to specify augmentation for the same case, though within the same file the last specification is taken. When augmentations for a case exist within both one .update.yml and one .yml file, the .update.yml is used (with the goal of updating the .yml file with the new augmentation values).

Methods of this class depend on the class-level presence of CASE_PRIMARY_KEYS, which is not provided in this class. To use this class’s functionality, derive from it and define this constant in the subclass. Two basic subclasses are defined in this module: HTTPCaseAugmenter and RPCCaseAugmenter.

__init__(augmentation_data_dir)

Constructing an instance

Parameters:augmentation_data_dir – path to directory holding the augmentation data

UPDATE_FILE_EXT = '.update.yml'

augmentation_data_dir

augmented_test_case(test_case)

Add key/value pairs to test_case per the stored augmentation data

Parameters:test_case (dict) – The test case to augment Returns:Test case with additional key/value pairs Return type:dict

augmented_test_case_events(case_key, case_id_events)

Generate YAML events for a test case

Parameters:

• case_key (str) – The case key for augmentation
• case_id_events – An iterable of YAML events representing the key/value pairs of the test case identity

This is used internally when extending an updates file with the existing data from a case, given the ID of the case as YAML.

extend_updates(file_name_base)

Create an object for extending a particular update file

The idea is:

case_augmenter.extend_updates('foo').with_current_augmentation(sys.stdin)

classmethod key_of_case(test_case)

Compute the key (hash) value of the given test case

safe_loading = True

update_compact_files()

Update compact data files from update data files

class intercom_test.framework.HTTPCaseAugmenter(augmentation_data_dir)

Bases: intercom_test.framework.CaseAugmenter

A CaseAugmenter subclass for augmenting HTTP test cases

CASE_PRIMARY_KEYS = frozenset({'method', 'request body', 'url'})

class intercom_test.framework.InterfaceCaseProvider(spec_dir, group_name, *, case_augmenter=None)

Bases: object

Test case data manager

Use an instance of this class to:

• Generate test case data dicts
• Decorate the case runner function (if auto-updating of compact augmentation data files is desired)
• Merge extension test case files to the main test case file
• Other case augmentation management tasks

Setting use_body_type_magic to True automatically parses the "request body" value as JSON if "request type" in the same test case is "json", and similarly for "response body" and "response type".

__init__(spec_dir, group_name, *, case_augmenter=None)

Constructing an instance

Parameters:

• spec_dir – File system directory for test case specifications
• group_name – Name of the group of tests to load
• case_augmenter – optional An object providing the interface of a CaseAugmenter

The main test case file of the group is located in spec_dir and is named for group_name with the ‘.yml’ extension added. Extension test case files are found in the group_name subdirectory of spec_dir and all have ‘.yml’ extensions.

case_augmenter

The CaseAugmenter instance used by this object, if any

case_runners(fn, *, do_compact_updates=True)

Generates runner callables from a callable

The callables in the returned iterable each call fn with all the positional arguments they are given, the test case dict as an additional positional argument, and all keyword arguments passed to the case runner.

Using this method rather than cases() directly for running tests has two advantages:

• The default of do_compact_updates automatically applies update_compact_augmentation_on_success() to fn
• Each returned runner callable will log the test case as YAML prior to invoking fn, which is helpful when updating the augmenting data for the case becomes necessary

cases()

Generates dicts of test case data

This method reads test cases from the group’s main test case file and auxiliary files, possibly extending them with augmented data (if case_augmentations was given in the constructor).

extension_files()

Get an iterable of the extension files of this instance

group_name

Name of group of test cases to load for this instance

main_group_test_file

Path to the main test file of the group for this instance

merge_test_extensions()

Merge the extension files of the target group into the group’s main file

spec_dir

The directory containing the test specification files for this instance

update_compact_augmentation_on_success(fn)

Decorator for activating compact data file updates

Using this decorator around the test functions tidies up the logic around whether to propagate test case augmentation data from update files to compact files. The compact files will be updated if all interface tests succeed and not if any of them fail.

The test runner function can be automatically wrapped with this functionality through case_runners().

update_compact_files()

Calls the CaseAugmenter to apply compact data file updates

Raises:NoAugmentationError – when no case augmentation data was specified during construction of this object

use_body_type_magic = False

class intercom_test.framework.RPCCaseAugmenter(augmentation_data_dir)

Bases: intercom_test.framework.CaseAugmenter

A CaseAugmenter subclass for augmenting RPC test cases

CASE_PRIMARY_KEYS = frozenset({'endpoint', 'request parameters'})

class intercom_test.framework.UpdateExtender(file_name_base, case_augmenter, *, safe_loading=None)

Bases: object

file_name

safe_loading = True

with_current_augmentation(stream)

Append the full test case with its current augmentation data to the target file

Parameters:stream – A file-like object (which could be passed to yaml.parse())

The stream contains YAML identifying the test case in question. The identifying YAML from the test case _plus_ the augmentative key/value pairs as currently defined in the augmenting data files will be written to the file file_name.

intercom_test.framework.data_files(dir_path)

Generate data file paths from the given directory

intercom_test.framework.extension_files(spec_dir, group_name)

Iterator of file paths for extensions of a test case group

Parameters:

• spec_dir – Directory in which specifications live
• group_name – Name of the group to iterate