intercom_test.framework module

class intercom_test.framework.CaseAugmenter(augmentation_data_dir)[source]

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.


Constructing an instance

Parameters:augmentation_data_dir – path to directory holding the augmentation data
UPDATE_FILE_EXT = '.update.yml'

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)[source]

Generate YAML events for a test case

  • 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.


Create an object for extending a particular update file

The idea is:

classmethod key_of_case(test_case)[source]

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

safe_loading = True

Update compact data files from update data files

class intercom_test.framework.HTTPCaseAugmenter(augmentation_data_dir)[source]

Bases: intercom_test.framework.CaseAugmenter

A CaseAugmenter subclass for augmenting HTTP test cases

CASE_PRIMARY_KEYS = frozenset({'request body', 'url', 'method'})
class intercom_test.framework.InterfaceCaseProvider(spec_dir, group_name, *, case_augmenter=None)[source]

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)[source]

Constructing an instance

  • spec_dir – File system directory for test case specifications
  • group_name – Name of the group of tests to load
  • case_augmenteroptional 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.


The CaseAugmenter instance used by this object, if any

case_runners(fn, *, do_compact_updates=True)[source]

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

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).


Get an iterable of the extension files of this instance


Name of group of test cases to load for this instance


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


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

safe_yaml_loading = True

The directory containing the test specification files for this instance


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().


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)[source]

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)[source]

Bases: object

safe_loading = True

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.


Generate data file paths from the given directory

intercom_test.framework.extension_files(spec_dir, group_name)[source]

Iterator of file paths for extensions of a test case group

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