Chrome OS VM for Chromium developers

Warning: This document is old & has moved. Please update any links:
https://chromium.googlesource.com/chromiumos/docs/+/HEAD/cros_vm.md

This workflow allows developers with a Chromium checkout using Simple Chrome to download and launch a Chrome OS VM on their workstations, update the VM with locally built Chrome, and run various tests.

Prerequisites

Virtualization check

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 this fails, check the Virtualization enabled doc for instructions.

For Goobuntu HP Zx20, interrupt the BIOS bootup with Esc for Options, F10 for Computer Setup, in the Security menu, System Security tab, Enable Virtualization Technology in the overlay.

Typography conventions

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

Download the VM

cd to your Chromium repository, and enter the Simple Chrome SDK environment with --download-vm:

(shell) .../chrome/src $ cros chrome-sdk --board=amd64-generic \
--download-vm --clear-sdk-cache --log-level=info

chrome-sdk options

--download-vm downloads a pre-packaged VM and QEMU (takes a few minutes).
--clear-sdk-cache recommended, clears the cache.
--log-level=debug for additional output (e.g. VM image download details).
--board=betty will download an ARC-enabled VM (Googler-only). There are variants for each Android versions and you need to pick the correct board name if you need to trouble shoot ARC++ related issues.
--chrome-branding will set $GN_ARGS to build and deploy a branded Chrome build including resources and components from src-internal.
--version to download a non-LKGM version, eg 10070.0.0. To find out available versions for a specific board, see Tips.
--use-external-config to use the public builders.

Some boards do not generate VM images. amd64-generic and betty (for ARC, internal only) are recommended. Using cros_vm for non-X86 boards is currently not supported.

Launch a Chrome OS VM

From within the Simple Chrome environment:

(sdk) .../chrome/src $ cros_vm --start

To avoid having to type your password everytime you launch a VM, add yourself to the kvm group: sudo usermod -a -G kvm $USER

Viewing the VM

To view the VM in a window, you can launch vncviewer:

(shell) vncviewer localhost:5900 &

To install vncviewer:

(shell) sudo apt-get install vncviewer

If this package is not available on your system, any other VNC Viewer should work as well. You can also use the VNC Viewer extension in chrome.

Stop the VM

(sdk) .../chrome/src $ cros_vm --stop

Remotely run a smoke test in the VM

(sdk) .../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.

Note that the CrOS test private RSA key cannot be world readable, so you may need to do:

(shell) .../chrome/src $ chmod 600 ./third_party/chromite/ssh_keys/testing_rsa

SSH into the VM

(shell) .../chrome/src $  ssh root@localhost -p 9222

Password is test0000

To avoid having to type a password and skip the RSA key warning:

(shell) .../chrome/src $ ssh -o UserKnownHostsFile=/dev/null -o \
StrictHostKeyChecking=no -i ./third_party/chromite/ssh_keys/testing_rsa \
root@localhost -p 9222

Run a local smoke test in the VM

(vm) localhost ~ # /usr/local/autotest/bin/vm_sanity.py

Run Telemetry Tests

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]

Update Chrome in the VM

Build Chrome

For testing local Chrome changes on Chrome OS, use the Simple Chrome flow to build Chrome (after entering the Simple Chrome SDK environment as described above):

(sdk) .../chrome/src $ autoninja -C out_$SDK_BOARD/Release/ \
chromiumos_preflight

Launch the VM

(sdk) .../chrome/src $ cros_vm --start

Deploy your Chrome to the VM

(sdk) .../chrome/src $ deploy_chrome --build-dir=out_$SDK_BOARD/Release/ \
--device=localhost:9222

Run a Tast test in the VM

Tast tests are typically executed from within a Chrome OS chroot:

(chroot) ~/trunk/src/scripts $ tast run -build=false localhost:9222 ui.ChromeLogin

You can also run Tast tests directly in the VM:

(vm) localhost ~ # local_test_runner ui.ScreenLock

See the Tast: Running Tests document for more information.

Run an ARC test in the VM

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) ~/trunk/src/scripts $ tast run -build=false localhost:9222 arc.Downloads

Run a Chrome GTest binary in the VM

The following will create a wrapper script at out_$SDK_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_$SDK_BOARD/Release/ $TEST
(sdk) .../chrome/src $ ./out_$SDK_BOARD/Release/bin/run_$TEST

Run a GPU test in the 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>

Login and navigate to a webpage in the VM

(vm) localhost ~ # /usr/local/autotest/bin/autologin.py \
--url "http://www.google.com/chromebook"

Launch a VM built by a waterfall bot

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_qemu_image.tar.xz to ~/Downloads/

Unzip:

(shell) $ tar xvf ~/Downloads/chromiumos_qemu_image.tar.xz

Launch a VM from within the Simple Chrome environment:

(sdk) .../chrome/src $ cros_vm --start \
--image-path  ~/Downloads/chromiumos_qemu_image.bin

Launch a locally built VM from within the chroot

Follow instructions to build Chromium OS and a VM image. In the chroot:

(chroot) ~/trunk/src/scripts $ export BOARD=betty
(chroot) ~/trunk/src/scripts $ ./build_packages --board=$BOARD
(chroot) ~/trunk/src/scripts $ ./build_image \
--noenable_rootfs_verification test --board=$BOARD
(chroot) ~/trunk/src/scripts $ ./image_to_vm.sh --test_image --board=$BOARD

You can specify the image path, and if you leave it out, the latest built image will be used:

(chroot) ~/trunk/src/scripts $ cros_vm --start --board $BOARD --image-path \
../build/images/$BOARD/latest/chromiumos_qemu_image.bin
(chroot) ~/trunk/src/scripts $ 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_test`

cros_run_test runs various tests in a VM. It can use an existing VM or launch a new one.

In Simple Chrome

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_$SDK_BOARD/Release

To run a Tast test:

(sdk) .../chrome/src $ cros_run_test --tast ui.ChromeLogin

To build and run an arbitrary test (e.g. base_unittests):

(sdk) .../chrome/src $ cros_run_test --build --chrome-test -- \
out_$SDK_BOARD/Release/base_unittests

In the chroot

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) ~/trunk/src/scripts $ cros_run_test --board $BOARD --tast ui.ChromeLogin

To run all Tast tests matched by an attribute expression:

(chroot) ~/trunk/src/scripts $ mkdir /tmp/results
(chroot) ~/trunk/src/scripts $ 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.

Tips

To lookup release versions for a particular board (e.g. betty):

(shell) .../chrome/src $ gsutil ls gs://chromeos-image-archive/betty-release/