Document how trial finds tests to run

[Screwtape]

I've been on a bit of a trial documentation kick recently, and noticed that neither the ​man page nor the ​HTML docs discuss the algorithm trial uses when looking for test files.

For example, if I run:

trial my.python.package

then which of the following tests will be found?

• TestCases defined in my/python/package/__init__.py
• TestCases defined in my/python/package/test_foo.py
• TestCases defined in my/python/package/Test_foo.py
• TestCases defined in my/python/package/testfoo.py
• TestCases defined in my/python/package/Testfoo.py
• TestCases defined in my/python/package/foo_test.py

For freshly-written tests designed to work with Trial, I personally always use the test_foo.py variant, but sometimes when I want to use Trial's test-sniffing features with third-party libraries, or to test legacy code I've inherited, it would be nice to have a place where I could find out definitively what the rules are.

(yes, I suppose I could just run Trial and see, but sometimes it's easier to try nosetests or py.test or run things manually than decipher exactly what failure-mode caused a particular error message)

[E. Dunham]

The answer to this actually is ​in the docs, just hidden pretty well. Whether a test is run depends not on what file it's in, but on how your module is configured and what its class inherits from.

I guess that references to that documentation should be added to at least the ​documentation and possibly the man page as well.

[E. Dunham]

The man page links the howto page from "see also", so no changes to the man page are required. Attached above is a patch which adds a link to the module loader docs from the testing howto.

[Adi Roiban]

Thanks for the work on this.

The patch needs a news file. ​http://twistedmatrix.com/trac/wiki/ReviewProcess#Newsfiles

The preferred format is diff without prefix ​http://twistedmatrix.com/trac/wiki/GitMirror#CreatingaGitclone

Other than that, it looks good.

Thanks!

[Adam Dangoor]

edunham's work with a NEWS file

[Adam Dangoor]

Hopefully I am not stepping on anyone's toes picking up the ticket edunham has worked on. I have addressed adiroiban's comments by adding a patch with a NEWS file and I used the patch-making instructions from https://twistedmatrix.com/trac/wiki/BasicGuideToContributingCode#SubmitaPatch.

[Richard Wall]

(In [43147]) Branching to trial-discovery-documentation-4526.

[Adi Roiban]

All good! Please merge this! Thanks!

[Adi Roiban]

(In [43735]) Branching to trial-discovery-documentation-4526-2.

[Adi Roiban]

I will sync with trunk and hope is ok... old branch was failing on buildbot

[Adi Roiban]

(In [43737]) Merge trial-discovery-documentation-4526-2: Update trial documentation.

Author: adamtheturtle Reviewers: adiroiban Fixes: #4526

Update trial documentation with link to how trial discover tests.

[Jean-Paul Calderone]

Don't forget to remove the review keyword when you review a ticket.

Also, the news fragment for this change seems to contain a mistake:

Twisted Trial's basics documentation now has a link to the documentation about how Trial finds tests.
Twisted Trial's basics documentation now has a link to the documentation about how Trial finds tests.

Separately, I'm not sure I'd consider this one line doc addition (which is just a reference to other existing documentation) non-misc material.

[Adi Roiban]

hawkowl fixed this in #7335 as the duplicate news line was already merged. I am sorry for letting this pass the review and merged in trunk.

I will remove the review in the future. Thanks for the help!