Working with Smother Data¶
Querying¶
Once you have build a .smother file, you can query it in
a variety of ways. It’s main usage is to lookup which tests
ran a particular section of code. This is what smother lookup
is for. The lookup command takes a description of a code section
in a variety of formats:
# module name. Matches the entire module
smother lookup smother.python
# module_name:line_number. Matches 1 line
smother lookup smother.python:50
# line range
smother lookup smother.python:50-60
# module:class_or_function
smother lookup smother.python:PythonFile
# module:nested_class_or_function
smother lookup smother.python:PythonFile.line_count
Smother determines which line range each section corresponds to, and prints out all of the tests which visited that region.
Semantic vs Literal Mode¶
By default, the code sections above are converted to a range of line
numbers, and smother looks for tests which also visit these line numbers.
However smother also takes a --semantic keyword. In semantic mode,
regions are expanded into the smallest function, class, or module
definition that contains the entire region. For example, consider
a particular line in smother’s source.
The following lines all expand to the same section of code in semantic mode:
smother --semantic lookup smother.python:34
smother --semantic lookup smother.python:24-38
smother --semantic lookup smother.python:Visitor.__init__
This is primarily useful for diff reporting and CSV output (below), but can be enabled manually in any context.
Diff Reporting¶
A common use case for smother is to determine, given a code change,
which tests might have broken. If the code is in a git repository,
smother provides a diff command to do this:
smother diff
smother diff origin/master
The behavior of the diff command is as follows:
- Determine which semantic regions were modified (deleted) in the old version of the code.
- Determine which semantic regions were modified (added) in the new version of the code.
- Take the union of these semantic regions – call this
U.- Report which tests visited region
U, assuming that the smother report was generated against the old version of the code.
Note that semantic mode is implied by the diff command.
CSV Dumps¶
Smother provides a csv command to dump each (source,test) pair
to a CSV file. Each source record will be a line number or,
if --semantic mode is enabled, a semantic region (module, class, or
function block). This can be used to more easily analyze the coupling
between app and test logic.
Coverage Reports¶
the to_coverage command converts a .smother datafile into a coverage.py datafile, for use with coverage.