blob: aacb9823ae8c7346d9fd11b88787a4dd5466be8d [file] [log] [blame] [view]
Chong Gu4749ec12021-02-17 01:41:061# Deploying and running gtests on Fuchsia.
2
3Fuchsia gtest binaries are deployed and executed via scripts that are
4automatically generated by the `fuchsia_package_runner()` GN target.
5The binaries can deploy to either emulators started by the runner script,
6an existing emulator instance, or a physical device. To build a gtest binary,
7check this [documentation](build_instructions.md).
8
9For the sake of this example, we will be using `base_unittests` as the package
10we wish to install and/or execute.
11
12## Hermetic emulation
13
14The test script brings up an emulator, runs the tests on it, and
15shuts the emulator down when finished.
16```bash
17$ out/fuchsia/bin/run_base_unittests
18```
19
20## Run on an physical device
21
22Note 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
30Make sure that the CPU architecture of your Chromium output directory matches
31the 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
38If you are frequently deploying to Fuchsia built from source, you might want to
39add the following entry to your `args.gn`:
40
41```
42default_fuchsia_build_dir_for_installation = "/path/to/fuchsia/outdir"
43```
44
45With this flag in place, the `--fuchsia-out-dir` flag will automatically be
46used whenever you `run_` or `install_` Fuchsia packages, making your command
47lines 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
60You will need to run the package manually on your device. In this case, run the
61following 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
69Note the `--ssh-config` flag, which should point to the config file used to set
70up 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
79To troubleshoot a specific test, consider a combination of the following
80arguments 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.