1# Test Runner Developer Guide 2 3Learn about test runners and how to create a new test runner class. 4 5##### Table of Contents 61. [Test Runner Details](#test-runner-details) 72. [Creating a Test Runner](#creating-a-test-runner) 8 9## <a name="test-runner-details">Test Runner Details</a> 10 11The test runner class is responsible for test execution. Its primary logic 12involve construction of the commandline given a ```TestInfo``` and 13```extra_args``` passed into the ```run_tests``` method. The extra_args are 14top-level args consumed by atest passed onto the test runner. It is up to the 15test runner to translate those args into the specific args the test runner 16accepts. In this way, you can think of the test runner as a translator between 17the atest CLI and your test runner's CLI. The reason for this is so that atest 18can have a consistent CLI for args instead of requiring the users to remember 19the differing CLIs of various test runners. The test runner should also 20determine its specific dependencies that need to be built prior to any test 21execution. 22 23## <a name="creating-a-test-runner">Creating a Test Runner</a> 24 25First thing to choose is where to put the test runner. This will primarily 26depend on if the test runner will be public or private. If public, 27```test_runners/``` is the default location. 28 29> If it will be private, then you can 30> follow the same instructions for ```vendorsetup.sh``` in 31> [constants override](atest_structure.md#constants-override) where you will 32> add the path of where the test runner lives into ```$PYTHONPATH```. Same 33> rules apply, rerun ```build/envsetup.sh``` to update ```$PYTHONPATH```. 34 35To create a new test runner, create a new class that inherits 36```TestRunnerBase```. Take a look at ```test_runners/example_test_runner.py``` 37to see what a simple test runner will look like. 38 39**Important Notes** 40You'll need to override the following parent methods: 41* ```host_env_check()```: Check if host environment is properly setup for the 42 test runner. Raise an expception if not. 43* ```get_test_runner_build_reqs()```: Return a set of build targets that need 44 to be built prior to test execution. 45* ```run_tests()```: Execute the test(s). 46 47And define the following class vars: 48* ```NAME```: Unique name of the test runner. 49* ```EXECUTABLE```: Test runner command, should be an absolute path if the 50 command can not be found in ```$PATH```. 51 52There is a parent helper method (```run```) that should be used to execute the 53actual test command. 54 55Once the test runner class is created, you'll need to add it in 56```test_runner_handler``` so that atest is aware of it. Try-except import the 57test runner in ```_get_test_runners``` like how ```ExampleTestRunner``` is. 58```python 59try: 60 from test_runners import new_test_runner 61 test_runners_dict[new_test_runner.NewTestRunner.NAME] = new_test_runner.NewTestRunner 62except ImportError: 63 pass 64``` 65