This workflow allows developers with a Chromium checkout using Simple Chrome to download and launch a ChromeOS VM on their workstations, update the VM with locally built Chrome, and run various tests.
To check if kvm is already enabled:
(shell) if [[ -e /dev/kvm ]] && grep '^flags' /proc/cpuinfo | grep -qE 'vmx|svm'; then echo 'KVM is working'; else echo 'KVM not working'; fi
If KVM is not working it must be enabled, which usually requires ensuring that your system firmware (BIOS) has virtualization features enabled and KVM is enabled in your kernel.
Googlers: check the Virtualization enabled doc for instructions.
| Label | Paths, files, and commands |
|---|---|
| (shell) | on your build machine, outside the sdk/chroot |
| (sdk) | inside the chrome-sdk Simple Chrome shell |
| (chroot) | inside the cros_sdk chroot |
| (vm) | inside the VM ssh session |
If you're just getting started, choose one of these:
Some boards do not generate VM images. Also, using cros vm for non-x86 boards is currently not supported.
The rest of these instructions assume you set an environment variable with your board. If you always use the same board you can just type it into each command.
(shell) .../chrome/src $ export BOARD=betty
cd to your Chromium repository:
(shell) $ cd chrome/src
Ensure your ../.gclient file looks something like this:
solutions = [
{
"name": "src",
"url": "https://chromium.googlesource.com/chromium/src.git",
"managed": False,
"custom_deps": {},
"custom_vars": {
# Downloads the SDK and VM image:
"cros_boards_with_qemu_images": "betty", # or "amd64-generic-vm"
},
},
]
target_os=['chromeos']
Googlers may wish to add the following to “custom_vars”:
"checkout_src_internal": True,
Then run gclient sync to download the SDK and VM image:
(shell) .../chrome/src $ gclient sync
This will create an out_betty/Release directory, which you'll use later.
(shell) .../chrome/src $ cros vm --start --board=$BOARD
To avoid having to type your password everytime you launch a VM, add yourself to the kvm group: sudo usermod -a -G kvm $USER
To view the VM in a window, you can launch vncviewer:
(shell) vncviewer localhost:5900 &
To install vncviewer:
(shell) sudo apt-get install vncviewer
See the ChromiumOS developer guide for additional options.
(shell) .../chrome/src $ cros vm --stop
(shell) .../chrome/src $ cros vm --cmd -- /usr/local/autotest/bin/vm_sanity.py
The command output in the VM will be output to the console after the command completes. Other commands run within an ssh session can also run with --cmd.
(shell) .../chrome/src $ cros shell localhost:9222
(vm) localhost ~ # /usr/local/autotest/bin/vm_sanity.py
To run telemetry functional or performance tests:
(shell) .../chrome/src $ third_party/catapult/telemetry/bin/run_tests \ --browser=cros-chrome --remote=localhost --remote-ssh-port=9222 [test] (shell) .../chrome/src $ tools/perf/run_tests \ --browser=cros-chrome --remote=localhost --remote-ssh-port=9222 [test]
Alternatively, to run these tests in local mode instead of remote mode, SSH into the VM as above, then invoke run_tests:
(vm) localhost ~ # python \ /usr/local/telemetry/src/third_party/catapult/telemetry/bin/run_tests [test] (vm) localhost ~ # python /usr/local/telemetry/src/tools/perf/run_tests [test]
For testing local Chrome changes on ChromeOS, use the Simple Chrome shell-less flow to build Chrome. Ensure your .gclient file looks like the one at the start of this page.
Syncing your source will now download the correct SDK toolchain for tip-of-trunk chrome and create the out_$BOARD/Release directory for you.
(shell) .../chrome/src $ git rebase-update (shell) .../chrome/src $ gclient sync -D # deletes unused dependencies (shell) .../chrome/src $ ls out_$BOARD/Release
You may wish to edit your out_$BOARD/Release/args.gn to something like:
import("//build/args/chromeos/betty.gni") # or amd64-generic-vm.gni
# Place any additional args or overrides below:
dcheck_always_on = true
is_debug = false
# For Googlers:
is_chrome_branded = true
use_goma = true
Then use gn to generate your ninja file and build:
(shell) .../chrome/src $ gn gen out_$BOARD/Release/ (shell) .../chrome/src $ autoninja -C out_$BOARD/Release/ \ chromiumos_preflight
(shell) .../chrome/src $ cros vm --start --board=$BOARD
(shell) .../chrome/src $ ./third_party/chromite/bin/deploy_chrome \ --build-dir=out_$BOARD/Release/ \ --device=localhost:9222
Tast tests are typically executed from within a ChromeOS chroot:
(chroot) $ tast run -build=false localhost:9222 login.Chrome
You can also run Tast tests directly in the VM:
(shell) .../chrome/src $ cros shell localhost:9222 (vm) localhost ~ # local_test_runner example.Pass
See the Tast: Running Tests document for more information.
Download the betty VM:
(sdk) .../chrome/src $ cros chrome-sdk --board=betty --download-vm
Run an ARC test:
(vm) localhost ~ # local_test_runner arc.Boot
Run a different ARC test from within your chroot:
(chroot) $ tast run -build=false localhost:9222 arc.Downloads
The following will create a wrapper script at out_$BOARD/Release/bin/ that can be used to launch a VM, push the test dependencies, and run the GTest. See the chromeos-amd64-generic-rel builder on Chromium's main waterfall for the list of GTests currently running in VMs (eg: base_unittests, ozone_unittests).
(sdk) .../chrome/src $ autoninja -C out_$BOARD/Release/ $TEST (sdk) .../chrome/src $ ./out_$BOARD/Release/bin/run_$TEST --use-vm
The following will run GPU tests that matches <glob-file-pattern>.
(sdk) .../chrome/src $ content/test/gpu/run_gpu_integration_test.py \ webgl_conformance --show-stdout --browser=cros-chrome --passthrough -v \ --extra-browser-args='--js-flags=--expose-gc --force_high_performance_gpu' \ --read-abbreviated-json-results-from=content/test/data/gpu/webgl_conformance_tests_output.json \ --remote=127.0.0.1 --remote-ssh-port=9222 --test-filter=<glob-file-pattern>
(vm) localhost ~ # /usr/local/autotest/bin/autologin.py \ --url "http://www.google.com/chromebook"
Select a full or release canary builder of interest. Note that not all of these bots build an image compatible with QEMU, so you'll likely want some flavor of amd64-generic or betty. Pick one of their builds, click on artifacts, and download chromiumos_test_image.tar.xz to ~/Downloads/
Unzip:
(shell) $ tar xvf ~/Downloads/chromiumos_test_image.tar.xz
Launch a VM:
(shell) .../chrome/src $ cros vm --start \ --image-path ~/Downloads/chromiumos_test_image.bin
Follow instructions to build ChromiumOS and a VM image. In the chroot:
(outside) $ export BOARD=betty # or amd64-generic (not amd64-generic-vm) (outside) $ cros build-packages --board=$BOARD (outside) $ cros build-image --no-enable-rootfs-verification test --board=$BOARD
You can specify the image path, and if you leave it out, the latest built image will be used:
(chroot) $ cros vm --start --board $BOARD --image-path \ ../build/images/$BOARD/latest/chromiumos_test_image.bin (chroot) $ cros vm --start --board $BOARD
You can also launch the VM from anywhere within your chromeos source tree:
(shell) .../chromeos $ chromite/bin/cros vm --start --board $BOARD
cros_run_testcros_run_test runs various tests in a VM. It can use an existing VM or launch a new one.
Enter the Simple Chrome SDK environment. Note that if you're using the recommended shell-less flow this will overwrite your args.gn (but with something reasonable).
(shell) .../chrome/src $ cros chrome-sdk --board=$BOARD
To launch a VM and run a smoke test:
(sdk) .../chrome/src $ cros_run_test
To build chrome, deploy chrome, or both, prior to running tests:
(sdk) .../chrome/src $ cros_run_test --build --deploy --build-dir \ out_$BOARD/Release
To run a Tast test:
(sdk) .../chrome/src $ cros_run_test --tast login.Chrome
To build and run an arbitrary test (e.g. base_unittests):
(sdk) .../chrome/src $ cros_run_test --build --chrome-test -- \ out_$BOARD/Release/base_unittests
These examples require a locally-built VM. See Launch a locally built VM from within the chroot.
To run an individual Tast test from within the chroot:
(chroot) $ cros_run_test --board $BOARD --tast login.Chrome
To run all Tast tests matched by an attribute expression:
(chroot) $ mkdir /tmp/results (chroot) $ cros_run_test --board $BOARD --results-dir=/tmp/results \ --tast '("group:mainline" && !informational)'
See go/tast-infra (Googler-only) for more information about which Tast tests are run by different builders.
This doc is at go/cros-vm.
To lookup release versions for a particular board (e.g. betty):
(shell) .../chrome/src $ gsutil ls gs://chromeos-image-archive/betty-release/