Chrome OS VM for Chromium developers

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

Prerequisites

  1. depot_tools installed
  2. Linux Chromium checkout
  3. Virtualization enabled

Virtualization check

To check if kvm is already enabled:

(shell) sudo kvm-ok

If kvm-ok is not found, check the Virtualization enabled doc for alternate 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

LabelPaths, 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.
  • --debug for debug output.
  • --board=betty will download an ARC-enabled VM (Googler-only).
  • --internal will set $GN_ARGS to build and deploy an internal Chrome build.
  • --version to download a non-LKGM version, eg 10070.0.0.

Some boards do not generate VM images. amd64-generic and betty (for ARC, internal only) are recommended.

Launch a Chrome OS VM

From within the Simple Chrome environment:

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

Viewing the VM

To view the VM in a window, you may need to 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.

Stop the VM

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

Remotely run a sanity test in the VM

(sdk) .../chrome/src $ cros_vm --cmd -- /usr/local/autotest/bin/vm_sanity.py

The command output on 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 sanity test in the VM

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

Run telemetry unit tests

To run telemetry unit tests, or perf unit 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/ \
chrome chrome_sandbox nacl_helper

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/ --to=localhost --port=9222

Run an autotest in the VM

From inside your chroot:

(chroot) ~/trunk/src/scripts $ test_that localhost:9222 login_Cryptohome

Run an ARC++ test in the VM

Download the betty VM:

(sdk) .../chrome/src $ cros chrome-sdk --board=betty --download-vm

vm_sanity will detect and run an ARC++ test:

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

Run a cheets autotest from within your chroot:

(chroot) ~/trunk/src/scripts $ ./build_packages --board=betty
(chroot) ~/trunk/src/scripts $ test_that localhost:9222 \
cheets_ContainerMount

Launch a VM built by a waterfall bot

Find a waterfall bot of interest, such as amd64-generic-tot-chromium-pfq-informational, which is a FYI bot that builds TOT Chrome with TOT Chrome OS, or amd64-generic-chromium-pfq, which is an internal PFQ builder. Pick a build, 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 $ ./setup_board --board=$BOARD
(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

You can either specify the image path or the board:

(chroot) ~/trunk/src/scripts $ cros_vm --start --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_vm_test

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

To launch a VM and run a sanity test:

(sdk) .../chrome/src $ cros_run_vm_test

To build chrome, deploy chrome, or both, prior to running tests:

(sdk) .../chrome/src $ cros_run_vm_test --build --deploy --build-dir \
out_$SDK_BOARD/Release

To run a tast test:

(sdk) .../chrome/src $ cros_run_vm_test \
--cmd -- local_test_runner ui.ChromeSanity

To run an arbitrary test (for e.g. base_unittests), you would need to first build base_unittests, copy the dependencies (the .so files) to the VM, and run the test in the correct working directory:

(sdk) .../chrome/src $ autoninja -C out_$SDK_BOARD/Release base_unittests
(sdk) .../chrome/src $ ls out_$SDK_BOARD/Release/base_unittests \
out_$SDK_BOARD/Release/*.so > /tmp/files.txt
(sdk) .../chrome/src $ cros_run_vm_test --files-from /tmp/files.txt \
--cwd out_$SDK_BOARD/Release --cmd -- ./base_unittests

The set of files to transfer to the VM is specified via --files or --files-from, a working directory via --cwd and the test command to run via --cmd.

To run an individual autotest from within the chroot:

(chroot) ~/trunk/src/scripts $ cros_run_vm_test --board $BOARD \
--autotest test_LoginCryptohome

To run the autotest smoke suite:

(chroot) ~/trunk/src/scripts $ mkdir /tmp/results
(chroot) ~/trunk/src/scripts $ cros_run_vm_test --board $BOARD \
--results-dir=/tmp/results --autotest suite:smoke

This doc is at go/cros-vm. Please send feedback to achuith@chromium.org.