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