1# Test Finder Developer Guide
2
3Learn about test finders and how to create a new test finder class.
4
5##### Table of Contents
61. [Test Finder Details](#test-finder-details)
72. [Creating a Test Finder](#creating-a-test-finder)
8
9## <a name="test-finder-details">Test Finder Details</a>
10
11A test finder class holds find methods. A find method is given a string (the
12user input) and should try to resolve that string into a ```TestInfo``` object.
13A ```TestInfo``` object holds the test name, test dependencies, test runner, and
14a data field to hold misc bits like filters and extra args for the test.  The
15test finder class can hold multiple find methods. The find methods are grouped
16together in a class so they can share metadata for optimal test finding.
17Examples of metadata would be the ```ModuleInfo``` object or the dirs that hold
18the test configs for the ```TFIntegrationFinder```.
19
20**When should I create a new test finder class?**
21
22If the metadata used to find a test is unlike existing test finder classes,
23that is the right time to create a new class. Metadata can be anything like
24file name patterns, a special file in a dir to indicate it's a test, etc. The
25default test finder classes use the module-info.json and specific dir paths
26metadata (```ModuleFinder``` and ```TFIntegrationFinder``` respectively).
27
28## <a name="creating-a-test-finder">Creating a Test Finder</a>
29
30First thing to choose is where to put the test finder. This will primarily
31depend on if the test finder will be public or private. If public,
32```test_finders/``` is the default location.
33
34> If it will be private, then you can
35> follow the same instructions for ```vendorsetup.sh``` in
36> [constants override](atest_structure.md#constants-override) where you will
37> add the path of where the test finder lives into ```$PYTHONPATH```. Same
38> rules apply, rerun ```build/envsetup.sh``` to update ```$PYTHONPATH```.
39
40Now define your class and decorate it with the
41```test_finder_base.find_method_register``` decorator. This decorator will
42create a list of find methods that ```test_finder_handler``` will use to collect
43the find methods from your test finder class. Take a look at
44```test_finders/example_test_finder.py``` as an example.
45
46Define the find methods in your test finder class. These find methods must
47return a ```TestInfo``` object. Extra bits of info can be stored in the data
48field as a dict.  Check out ```ExampleFinder``` to see how the data field is
49used.
50
51Decorate each find method with the ```test_finder_base.register``` decorator.
52This is used by the class decorator to identify the find methods of the class.
53
54Final bit is to add your test finder class to ```test_finder_handler```.
55Try-except import it in the ```_get_test_finders``` method and that should be
56it. The find methods will be collected and executed before the default find
57methods.
58```python
59try:
60    from test_finders import new_test_finder
61    test_finders_list.add(new_test_finder.NewTestFinder)
62except ImportError:
63    pass
64```
65