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.
Installation¶
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.