Chong Gu | 4749ec1 | 2021-02-17 01:41:06 | [diff] [blame] | 1 | # Deploying and running gtests on Fuchsia. |
| 2 | |
| 3 | Fuchsia gtest binaries are deployed and executed via scripts that are |
| 4 | automatically generated by the `fuchsia_package_runner()` GN target. |
| 5 | The binaries can deploy to either emulators started by the runner script, |
| 6 | an existing emulator instance, or a physical device. To build a gtest binary, |
| 7 | check this [documentation](build_instructions.md). |
| 8 | |
| 9 | For the sake of this example, we will be using `base_unittests` as the package |
| 10 | we wish to install and/or execute. |
| 11 | |
| 12 | ## Hermetic emulation |
| 13 | |
| 14 | The test script brings up an emulator, runs the tests on it, and |
| 15 | shuts the emulator down when finished. |
| 16 | ```bash |
| 17 | $ out/fuchsia/bin/run_base_unittests |
| 18 | ``` |
| 19 | |
| 20 | ## Run on an physical device |
| 21 | |
| 22 | Note the `-d` flag, which is an alias for `--device`. |
| 23 | |
| 24 | ```bash |
| 25 | $ out/fuchsia/bin/run_base_unittests -d |
| 26 | ``` |
| 27 | |
| 28 | ## Run on a device paved with Fuchsia built from source |
| 29 | |
| 30 | Make sure that the CPU architecture of your Chromium output directory matches |
| 31 | the architecture of the Fuchsia output directory (x64==x64, arm64==arm64, etc.). |
| 32 | |
| 33 | ```bash |
| 34 | $ out/fuchsia/bin/run_base_unittests -d |
| 35 | --fuchsia-out-dir=/path/to/fuchsia/outdir |
| 36 | ``` |
| 37 | |
| 38 | If you are frequently deploying to Fuchsia built from source, you might want to |
| 39 | add the following entry to your `args.gn`: |
| 40 | |
| 41 | ``` |
| 42 | default_fuchsia_build_dir_for_installation = "/path/to/fuchsia/outdir" |
| 43 | ``` |
| 44 | |
| 45 | With this flag in place, the `--fuchsia-out-dir` flag will automatically be |
| 46 | used whenever you `run_` or `install_` Fuchsia packages, making your command |
| 47 | lines much shorter: |
| 48 | |
| 49 | ```bash |
| 50 | $ out/fuchsia/bin/run_base_unittests -d |
| 51 | ``` |
| 52 | |
| 53 | ## Install on a device running Fuchsia built from source |
| 54 | |
| 55 | ```bash |
| 56 | $ out/fuchsia/bin/install_base_unittests |
| 57 | --fuchsia-out-dir=/path/to/fuchsia/outdir |
| 58 | ``` |
| 59 | |
| 60 | You will need to run the package manually on your device. In this case, run the |
| 61 | following from your Fuchsia directory: |
| 62 | |
| 63 | ``` |
| 64 | $ fx shell run fuchsia-pkg://fuchsia.com/base_unittests#meta/base_unittests.cmx |
| 65 | ``` |
| 66 | |
| 67 | ## Run on a device the host is connected to remotely via ssh |
| 68 | |
| 69 | Note the `--ssh-config` flag, which should point to the config file used to set |
| 70 | up the connection between the host and the remote device. |
| 71 | |
| 72 | ```bash |
| 73 | $ out/fuchsia/bin/run_base_unittests -d |
| 74 | --host=localhost --ssh-config=/path/to/ssh/config |
| 75 | ``` |
| 76 | |
| 77 | ## Troubleshooting a test |
| 78 | |
| 79 | To troubleshoot a specific test, consider a combination of the following |
| 80 | arguments to the test runner script: |
| 81 | |
| 82 | * `--gtest_filter="[TestSuite.TestName]"` to only run a specific test, or a |
| 83 | comma-separated list to run a set of tests. Wildcards can also be used to run |
| 84 | a set of tests or an entire test suite, e.g. `--gtest_filter="[TestSuite.*]"`. |
| 85 | * `--test-launcher-jobs=1` to only have one batch of tests running at a time. |
| 86 | This bypasses the test launcher buffering of test log output, making it |
| 87 | possible to access the log output from successful test runs. |
| 88 | * `--single-process-tests` to run all the tests in the same process. Unlike the |
| 89 | above option, this will run the tests directly in the test launcher process, |
| 90 | making it easier to attach a debugger. |
| 91 | * `system-log-file=[/path/to/syslog]` to specify the file to write system logs |
| 92 | to. Or `system-log-file=-` to write the system logs to stdout. By default, |
| 93 | Chromium logs are written to the system log on Fuchsia. This argument is known |
| 94 | to cause `IOError` python exceptions with a QEMU target. |
| 95 | * `--gtest_repeat=[number] --gtest_break_on_failure` to run a test or test suite |
| 96 | a certain number of times until it fails. This is useful to investigate flaky |
| 97 | tests. |