sphinxcontrib.argdoc.test.test_argdoc module

Test suite for sphinxcontrib.argdoc.

Test implementation

• Unit tests are provided for regular expressions used to identify different patterns from argparse output

• Unit and functional tests e.g. for sphinxcontrib.argdoc.ext.format_argparser_as_docstring() are performed as follows:

  1. Sphinx is run on the test cases in sphinxcontrib.argdoc.test.cases using the reStructuredText (rst) document stubs and configuration file (conf.py) in sphinxcontrib/argdoc/test/testdocroot. rst stubs are automatically detected by Sphinx, and the corresponding executable scripts in sphinxcontrib.argdoc.test.cases auto-detected by TestArgdoc.
  2. The rst output is saved after sphinxcontrib.argdoc completes, before conversion to HTML (or other formats) by Sphinx. The rst output is compared against reference output that can be found in sphinxcontrib/argdoc/test/testbuild. Comparing the rst output makes the tests robust to potential changes in html rendering in Sphinx.

To add a test case for a new argparse configuration

1. Create an executable script using argparse following the general form of the other tests. Put it in the subpackage sphinxcontrib.argdoc.test.cases
2. Create a matching rst document stub, and put it into sphinxcontrib/argdoc/test/testdocroot
3. Add an entry for the rst document stub in sphinxcontrib/argdoc/test/testdocroot/master_toctree.rst

class sphinxcontrib.argdoc.test.test_argdoc.TestArgdoc

Test case for functions defined in sphinxcontrib.argdoc.ext

Methods

check_equal(expected, found[, casename])	Helper method just to allow us to use test generators in other tests
check_list_equal(l1, l2, test_name)
check_not_match(pattern, inp, msg)
check_pattern(test_name, pat, inp, expected)	Check patterns for matching, or non-matching
run_builder()	Run sphinx builder only the first time it is needed
setUpClass()
tearDownClass()	Clean up temp files after tests are complete
test_format_argparser_as_docstring()
test_get_col1_text()
test_get_col2_text()
test_make_rest_table_with_indent()
test_make_rest_table_with_title()
test_make_rest_table_without_title()
test_noargdoc_adds_attribute()
test_patterns()
test_post_process_automodule()
test_post_process_automodule_emits_event()
test_prefix_chars_does_not_match_wrong()
test_prefix_chars_does_not_mix()
test_prefix_chars_matches()

classmethod setUpClass()

classmethod tearDownClass()

Clean up temp files after tests are complete

classmethod run_builder()

Run sphinx builder only the first time it is needed

Raises:

AssertionError

If builder exists with non-zero status

static check_pattern(test_name, pat, inp, expected)

Check patterns for matching, or non-matching

Parameters:

test_name : str

Name of test set being executed

pat : re.compile

Pattern to test

inp : str

Input to test

expected : dict, tuple, or None

Expected result. If a dict, equivalence is tested with pat.match(inp).groupdict() is called to test equivalence. If a ‘tuple’ equivalence is tested with pat.match(inp).groups(), re.compile.groups() is called. If None, it is asserted that pat.match(inp) is None

test_patterns()

static check_equal(expected, found, casename='')

Helper method just to allow us to use test generators in other tests

test_prefix_chars_matches()

static check_not_match(pattern, inp, msg)

test_prefix_chars_does_not_match_wrong()

test_prefix_chars_does_not_mix()

test_get_col1_text()

test_get_col2_text()

test_make_rest_table_with_title()

test_make_rest_table_without_title()

test_make_rest_table_with_indent()

test_noargdoc_adds_attribute()

static check_list_equal(l1, l2, test_name)

test_format_argparser_as_docstring()

test_post_process_automodule()

test_post_process_automodule_emits_event()

class sphinxcontrib.argdoc.test.test_argdoc.Record

Bases: object

Proxy object that allows addition of arbitrary properties

__init__()

class sphinxcontrib.argdoc.test.test_argdoc.FakeApp(argdoc_main_func='main', argdoc_save_rst=True, outdir='/tmp/', argdoc_prefix_chars='-')

Bases: object

Proxy for a Sphinx application object. Implements minimial methods required for us to test functions in sphinxcontrib.argdoc.ext that require a Sphinx application instance

Methods

debug(*args, **kwargs)
debug2(*args, **kwargs)
emit(*args, **kwargs)	Simulate emit method.
warn(*args, **kwargs)

__init__(argdoc_main_func='main', argdoc_save_rst=True, outdir='/tmp/', argdoc_prefix_chars='-')

warn(*args, **kwargs)

debug(*args, **kwargs)

debug2(*args, **kwargs)

emit(*args, **kwargs)

Simulate emit method. Save event name in self.emitted at each call