icy-test Command Line Tool

Not every test harness is written in Python. To accommodate this, the intercom_test package can be installed to provide a command line tool call icy-test that provides access to the core functionality.


To install the icy-test command line tool, simply install intercom_test package with the [cli] extra, e.g.:

pip install intercom_test[cli]

This creates a command line tool named icy-test, which can be run with the --help flag to get usage information. This information will be the most recent and detailed available.

Configuration File

icy-test needs a configuration file to provide information that would, in a typical Python testing setting, be provided as parameters to the InterfaceCaseProvider constructor. The path to this file is specified with the -c or --config flag when running icy-test.

A text-mode helper for building a configuration file (which is a YAML file, usually with a .yml extension) is provided as icy-test init, and requires specifying a config file using one of the options mentioned above.

Consuming Test Cases

The main use of icy-test is to access the test cases. These are available in the output of icy-test enumerate in either a stream of YAML documents (one per test case) or as JSON Lines (each line contains a JSON document).

Committing Augmentation Data Updates

Where InterfaceCaseProvider used within a Python testing framework can provide case runners that can automatically update the compact augmentation data files when all test cases have passed, no such facility is easily implemented when consuming the test cases from another process and/or language. The augmentation data changes embodied in the update files need to be explicitly committed to the compact files by running icy-test commitupdates.

Merging Interface Extension Test Cases To Main File

Use the icy-test mergecases subcommand to invoke intercom_test.framework.InterfaceCaseProvider.merge_test_extensions() with appropriate setup taken from the icy-test configuration file.

Access HTTP JSON Exchange Stubs Outside Python

Because solutions involving exchanges of JSON documents over HTTP are becoming very popular, icy-test provides a subcommand to offload the logic of matching the elements of the HTTP request (method, URL (path and query string), and sometimes request body) with a test case. Moreover, icy-test hjx-stubber will, when given a request that doesn’t exist in the test case set, respond with information on how the request can be changed to one that is in the test case set.

If changing the method, URL, and request body do not provide enough dimensions of control to adequately represent the gamut of request/response pairs for the represented service, icy-test hjx-stubber does reference the request keys configuration file entry, which can be used to add fields to the “test case key.” An example would be listing story as a request key, then populating test cases that share the same method, URL, and request body with individual values for the the story field. To fully implement this, the interface-consuming project has to be willing to inject a story field into the request line passed to icy-test hjx-stubber during testing.

icy-test hjx-stubber accepts a request formatted as a JSON object on a single line (i.e. JSON Lines), where at least method and url properties are present. It will respond with a similar JSON Lines object which is either the full, matching test case (plus a response status field if one was not specified in the data files) or a set of diffs for the closest test cases icy-test hjx-stubber could find in the whole case set. See icy-test hjx-stubber --help for more information.

Starting up icy-test hjx-stubber is somewhat expensive for large sets of test cases, so it is best to start it when spinning up the test environment for a run of tests, then shut it down when testing finishes. Closing standard input is enough to get the program to exit.