commit ef7416255976b2885733c170a6bde0263a239254 Author: Damian Johnson atagar@torproject.org Date: Tue Sep 29 16:48:37 2020 -0700

Test that all examples are referenced

Our unused load_test.py makes it clear that we should check that all our examples are cited by the website. I can see myself making that mistake again. --- docs/tutorials/to_russia_with_love.rst | 2 +- stem/manual.py | 2 +- test/unit/examples.py | 35 ++++++++++++++++++++++++++++++++-- 3 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/docs/tutorials/to_russia_with_love.rst b/docs/tutorials/to_russia_with_love.rst index fc1b4d2c..af94185a 100644 --- a/docs/tutorials/to_russia_with_love.rst +++ b/docs/tutorials/to_russia_with_love.rst @@ -68,7 +68,7 @@ connections through Tor, so this'll break our ability to connect to Tor's control port. To use this approach simply replace the query() function above with...

-.. literalinclude:: /_static/example/client_usage_using_socksipy.py +.. literalinclude:: /_static/example/client_usage_using_socksipy.py :caption: `[Download] <../_static/example/client_usage_using_socksipy.py>`__ :language: python

diff --git a/stem/manual.py b/stem/manual.py index dbde9827..e7658317 100644 --- a/stem/manual.py +++ b/stem/manual.py @@ -21,7 +21,7 @@ Manual information includes arguments, signals, and probably most usefully the torrc configuration options. For example, say we want a little script that told us what our torrc options do...

-.. literalinclude:: /_static/example/manual_config_options.py +.. literalinclude:: /_static/example/manual_config_options.py :language: python

| diff --git a/test/unit/examples.py b/test/unit/examples.py index 094322e6..12ffb60c 100644 --- a/test/unit/examples.py +++ b/test/unit/examples.py @@ -7,6 +7,7 @@ import binascii import functools import io import os +import re import sys import unittest

@@ -231,13 +232,13 @@ class TestExamples(unittest.TestCase):

stem.descriptor.remote.SINGLETON_DOWNLOADER = None

- def test_runs_everything(self): + def test_everything_is_tested(self): """ Ensure we have tests for all our examples. """

all_examples = set([os.path.basename(path)[:-3] for path in stem.util.system.files_with_suffix(EXAMPLE_DIR, '.py')]) - tested_examples = set([method[5:] for method in dir(self) if method.startswith('test_') and method != 'test_runs_everything']) + tested_examples = set([method[5:] for method in dir(self) if method.startswith('test_') and not method.startswith('test_everything_')])

extra = sorted(tested_examples.difference(all_examples)) missing = sorted(all_examples.difference(tested_examples).difference(UNTESTED)) @@ -248,6 +249,36 @@ class TestExamples(unittest.TestCase): if missing: self.fail("Changed our examples directory? The following are untested: %s" % ', '.join(missing))

+ def test_everything_is_referenced(self): + """ + Ensure that all our examples are referenced our website. Otherwise they're + dead code. + """ + + all_examples = set([os.path.basename(path)[:-3] for path in stem.util.system.files_with_suffix(EXAMPLE_DIR, '.py')]) + + include_regex = re.compile('.. literalinclude:: /_static/example/(\S*).py') + referenced_examples = set() + + for path in stem.util.system.files_with_suffix(os.path.join(test.STEM_BASE, 'docs'), '.rst'): + with open(path) as example_file: + referenced_examples.update(include_regex.findall(example_file.read())) + + for path in stem.util.system.files_with_suffix(os.path.join(test.STEM_BASE, 'stem'), '.py'): + with open(path) as source_file: + referenced_examples.update(include_regex.findall(source_file.read())) + + extra = sorted(referenced_examples.difference(all_examples)) + missing = sorted(all_examples.difference(referenced_examples)) + + missing.remove('benchmark_stem') # expanded copy of benchmark_server_descriptor_stem.py + + if extra: + self.fail("Changed our documentation? We reference the following examples which are not present: %s" % ', '.join(extra)) + + if missing: + self.fail("Changed our documntation? The following examples are unreferenced: %s" % ', '.join(missing)) + @patch('stem.descriptor.remote.get_bandwidth_file') @patch('sys.stdout', new_callable = io.StringIO) def test_bandwidth_stats(self, stdout_mock, get_bandwidth_file_mock):