Documenting member functions exclusively starting with "test_"

Question

How can I document my tests, only my tests?

I document my unittest with Sphinx.

My setup is as followed:

class MyTestWrapper1(unittest.Testcase)
    def test_general_setup()

class MyTestWrapper2(MyTestWrapper1)
    def test_general_tear_down()

class TheUsedTest1(MyTestWrapper2)
    def test_specific_test()

As we can see the parent is Unittest.TestCase and all is derived by TheUsedTes1.

Now I'm going to document the class TheUsedTest1.

I would like to have all the member functions starting with test_ shown in the HTML output.

To archive that I've used the option :inherited-members: which actually displays all the test_* members. But it also displays ALL OTHER member functions from unittest too.

.. automodule:: TheUsedTes1
   :members:
   :inherited-members:

I've tried to add to my conf.py following snippet. It should skip special parts.

def maybe_skip_member(app, what, name: str, obj, skip, options):

    print(name, file=sys.stderr, end='')
    if name.startswith('test_'):
        print(".. OK", file=sys.stderr)
        return False
    else:
        print(".. nope", file=sys.stderr)
        return True

def setup(app):
    app.connect('autodoc-skip-member', maybe_skip_member)

But it does not work as expected. Every object which is iterated is killed, if it does not start with test_. How ever, if the iteration runs over TheUsedTest1 it's killed, and any member function is not respected. So it never reaches the members which should be documented.

MrBean Bremen · Answer 1 · 2020-07-14T18:25:24.817

0

I haven't tested this, but you could try to check for the type of the object to skip:

def maybe_skip_member(app, what, name: str, obj, skip, options):
    import inspect
    if inspect.isclass(obj) or name.startswith('test_'):
        return False
    return True

EDIT: changed that to only check for classes - otherwise all dunder methods and more attributes are also listed.

edited Jul 14 '20 at 18:25

answered Jul 14 '20 at 15:41

MrBean Bremen

14,916
3
26
46

First time I like a person with second name Bean... The result of the statement is that all entities are displayed. `test_` and those which don't. what comes with "what" is either a class or a module. Do you have any idea where to find documentation for those parameters? Or is it possible to actually debug in there? – Cutton Eye Jul 14 '20 at 17:24
Hm, that's strange - I just added this to an existing project and actually got listed all functions (using print-debugging, I have no idea how to debug this) and filtering by name also worked... obviously some configuration is different here. Note that `what` ia also `class` or `module` here - this seems to be the scope, not the type of the object, though I haven't found documentation either. – MrBean Bremen Jul 14 '20 at 18:05
I did some minor change after I noticed that too much has been passed - please check if that makes a difference for your case. – MrBean Bremen Jul 14 '20 at 18:26

Documenting member functions exclusively starting with "test_"

1 Answers1