docs/quickstart.md - chromiumos/platform/tast - Git at Google

 # Tast Quickstart (go/tast-quickstart)

 [TOC]

 ## Prerequisites

 You'll need a [ChromeOS chroot]. If you've only done Chrome development so far,
 note that this is different from the Chrome checkout described in the
 [Simple Chrome] documentation.

 You'll also need a ChromeOS device running a system image built with the `test`
 flag that's reachable from your workstation via SSH. An image running in a
 [virtual machine] will also work. If you're using a test image that you
 downloaded rather than one built in your chroot, make sure that it's a recent
 version.

 <a name="dataloss"></a> **WARNING: Potential data loss:**  Many Tast tests
 remove all user profiles from the device when run, including any local state.
 Prefer to have a device specifically for testing.

 [ChromeOS chroot]: https://www.chromium.org/chromium-os/developer-library/guides/development/developer-guide/#create-a-chroot
 [Simple Chrome]: https://www.chromium.org/chromium-os/developer-library/guides/development/simple-chrome-workflow
 [virtual machine]: https://www.chromium.org/chromium-os/developer-library/guides/containers/cros-vm

 ## Setup

 ### Update ChromeOS chroot

 Assuming that you already have a valid ChromeOS repo checked out (see
 [ChromeOS chroot]), it is recommended to update the chroot by doing:

 ```sh
 cd ${CHROMEOS_SRC}
 chromite/bin/cros_sdk    # to enter chroot
 ./update_chroot          # makes sure that the latest dependencies are installed
 ```

 ### IDE

 Any [modern editor] supports Go. The following are the instructions to setup
 [Visual Studio Code] with Tast code navigation:

 1.  Download [Visual Studio Code]
 2.  Install the [official Go extension] (VSCode will recommend that extension
     once you open a Go file), and optionally [CrOS IDE], which [among others]
     substitutes the step 3 and 4 once you open a Tast test file.
 3.  Update the `GOPATH` environment variable to make code navigation works (`F12` key)

     ```sh
     mkdir ~/go
     # Main GOPATH, where extra binaries will get installed.
     export GOPATH=$HOME/go
     # Append Tast repos to GOPATH
     export GOPATH=${GOPATH}:${CHROMEOS_SRC}/src/platform/tast-tests:${CHROMEOS_SRC}/src/platform/tast
     # Append Tast dependencies
     export GOPATH=${GOPATH}:${CHROMEOS_SRC}/chroot/usr/lib/gopath
     ```

 4.  Start Visual Studio Code with Tast

     ```sh
     cd ${CHROMEOS_SRC}/src/platform/
     code ./tast-tests ./tast
     ```

 Note: If you are using the VSCode "Remote-SSH" extension, restart
 VSCode's SSH server after setting the GOPATH, otherwise the Go
 extension won't pick it up. For example, using the VSCode command
 palette, you can run `>Remote-SSH: Kill VS Code Server on Host`.

 After that, it's useful to add the following to your settings JSON to
 avoid opening a 404 page whenever you try to follow links from import
 statements:

 ```
   "gopls": {
     "ui.navigation.importShortcut": "Definition"
   },
 ```

 https://github.com/golang/vscode-go/issues/237#issuecomment-646067281

 [modern editor]: https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins
 [Visual Studio Code]: https://code.visualstudio.com/
 [official Go extension]: https://code.visualstudio.com/docs/languages/go
 [CrOS IDE]: https://marketplace.visualstudio.com/items?itemName=Google.cros-ide
 [among others]: http://go/cros-ide-doc-tast-tests

 ## Run a prebuilt test

 **WARNING: Potential data loss:** Tast [may delete](#dataloss) profiles and
 local state.

 In your chroot, run the following:

 ```sh
 tast -verbose run -build=false <test-device-ip> login.Chrome
 ```

 You should see output scroll by on your workstation, and on the ChromeOS
 device, the test should log in and load a webpage. After the test is done, take
 a look at the results in `/tmp/tast/results/latest` in your chroot.

 ## Build and run a test

 **WARNING: Potential data loss:** Tast [may delete](#dataloss) profiles and
 local state.

 The previous step ran a test that was already built into your device's system
 image, but you can also use the `tast` command to quickly rebuild all tests and
 push them to the device.

 In your chroot, run the same command as before **but without the `-build=false`
 argument**:

 ```sh
 tast -verbose run <test-device-ip> login.Chrome
 ```

 This time, the command will take a bit longer (but build objects will be
 cached). The test should succeed again.

 See [Running Tests] for more information.

 [Running Tests]: running_tests.md

 ## Modify a test

 Now, let's modify the test. In your ChromeOS checkout, go to
 `src/platform/tast-tests/src/go.chromium.org/tast-tests/cros/local/bundles/cros/login` and open
 `chrome.go` (for convenience, there's also a `cros` symlink at the
 top of `tast-tests`). The `Chrome` function here will run directly on the
 test device.

 At the end of the function `testChromeLogin`, add the following code:

 ```go
 if _, err = cr.NewConn(ctx, "https://www.google.com/"); err != nil {
 	s.Error("Failed to open page: ", err)
 }
 ```

 Back in your chroot, run `tast` again:

 ```sh
 tast -verbose run <test-device-ip> login.Chrome
 ```

 This time, the test should additionally open a Google search page.

 Return to the test file and add the following statement at the end of the
 function `testChromeLogin`:

 ```go
 s.Error("This is an intentional error")
 ```

 If you build and run the test again, you should see it fail.

 ## Next steps

 See [Writing Tests] for more information, and explore the
 [tast-tests repository] to see existing tests and related packages. [Codelab #1]
 walks through the creation of a simple test.

 Additional Tast documentation is available in the [tast repository].

 Many resources are available for learning more about Go. Here are a few:

 *   [A Tour of Go] - In-browser introduction to Go's core features.
 *   [Official Go documentation] - Package documentation, specifications, blog
     posts, and recorded talks.
 *   [Go at Google: Language Design in the Service of Software Engineering] -
     High-level overview of Go's features and design philosophy.
 *   [Community Learn wiki] - Links to external resources.

 [Writing Tests]: writing_tests.md
 [tast-tests repository]: https://chromium.googlesource.com/chromiumos/platform/tast-tests/
 [Codelab #1]: codelab_1.md
 [tast repository]: https://chromium.googlesource.com/chromiumos/platform/tast/
 [A Tour of Go]: https://tour.golang.org/
 [Official Go documentation]: https://golang.org/doc/
 [Go at Google: Language Design in the Service of Software Engineering]: https://talks.golang.org/2012/splash.article
 [Community Learn wiki]: https://github.com/golang/go/wiki/Learn
	# Tast Quickstart (go/tast-quickstart)

	[TOC]

	## Prerequisites

	You'll need a [ChromeOS chroot]. If you've only done Chrome development so far,
	note that this is different from the Chrome checkout described in the
	[Simple Chrome] documentation.

	You'll also need a ChromeOS device running a system image built with the `test`
	flag that's reachable from your workstation via SSH. An image running in a
	[virtual machine] will also work. If you're using a test image that you
	downloaded rather than one built in your chroot, make sure that it's a recent
	version.

	<a name="dataloss"></a> WARNING: Potential data loss: Many Tast tests
	remove all user profiles from the device when run, including any local state.
	Prefer to have a device specifically for testing.

	[ChromeOS chroot]: https://www.chromium.org/chromium-os/developer-library/guides/development/developer-guide/#create-a-chroot
	[Simple Chrome]: https://www.chromium.org/chromium-os/developer-library/guides/development/simple-chrome-workflow
	[virtual machine]: https://www.chromium.org/chromium-os/developer-library/guides/containers/cros-vm

	## Setup

	### Update ChromeOS chroot

	Assuming that you already have a valid ChromeOS repo checked out (see
	[ChromeOS chroot]), it is recommended to update the chroot by doing:

	```sh
	cd ${CHROMEOS_SRC}
	chromite/bin/cros_sdk # to enter chroot
	./update_chroot # makes sure that the latest dependencies are installed
	```

	### IDE

	Any [modern editor] supports Go. The following are the instructions to setup
	[Visual Studio Code] with Tast code navigation:

	1. Download [Visual Studio Code]
	2. Install the [official Go extension] (VSCode will recommend that extension
	once you open a Go file), and optionally [CrOS IDE], which [among others]
	substitutes the step 3 and 4 once you open a Tast test file.
	3. Update the `GOPATH` environment variable to make code navigation works (`F12` key)

	```sh
	mkdir ~/go
	# Main GOPATH, where extra binaries will get installed.
	export GOPATH=$HOME/go
	# Append Tast repos to GOPATH
	export GOPATH=${GOPATH}:${CHROMEOS_SRC}/src/platform/tast-tests:${CHROMEOS_SRC}/src/platform/tast
	# Append Tast dependencies
	export GOPATH=${GOPATH}:${CHROMEOS_SRC}/chroot/usr/lib/gopath
	```

	4. Start Visual Studio Code with Tast

	```sh
	cd ${CHROMEOS_SRC}/src/platform/
	code ./tast-tests ./tast
	```

	Note: If you are using the VSCode "Remote-SSH" extension, restart
	VSCode's SSH server after setting the GOPATH, otherwise the Go
	extension won't pick it up. For example, using the VSCode command
	palette, you can run `>Remote-SSH: Kill VS Code Server on Host`.

	After that, it's useful to add the following to your settings JSON to
	avoid opening a 404 page whenever you try to follow links from import
	statements:

	```
	"gopls": {
	"ui.navigation.importShortcut": "Definition"
	},
	```

	https://github.com/golang/vscode-go/issues/237#issuecomment-646067281

	[modern editor]: https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins
	[Visual Studio Code]: https://code.visualstudio.com/
	[official Go extension]: https://code.visualstudio.com/docs/languages/go
	[CrOS IDE]: https://marketplace.visualstudio.com/items?itemName=Google.cros-ide
	[among others]: http://go/cros-ide-doc-tast-tests

	## Run a prebuilt test

	WARNING: Potential data loss: Tast [may delete](#dataloss) profiles and
	local state.

	In your chroot, run the following:

	```sh
	tast -verbose run -build=false <test-device-ip> login.Chrome
	```

	You should see output scroll by on your workstation, and on the ChromeOS
	device, the test should log in and load a webpage. After the test is done, take
	a look at the results in `/tmp/tast/results/latest` in your chroot.

	## Build and run a test

	WARNING: Potential data loss: Tast [may delete](#dataloss) profiles and
	local state.

	The previous step ran a test that was already built into your device's system
	image, but you can also use the `tast` command to quickly rebuild all tests and
	push them to the device.

	In your chroot, run the same command as before **but without the `-build=false`
	argument**:

	```sh
	tast -verbose run <test-device-ip> login.Chrome
	```

	This time, the command will take a bit longer (but build objects will be
	cached). The test should succeed again.

	See [Running Tests] for more information.

	[Running Tests]: running_tests.md

	## Modify a test

	Now, let's modify the test. In your ChromeOS checkout, go to
	`src/platform/tast-tests/src/go.chromium.org/tast-tests/cros/local/bundles/cros/login` and open
	`chrome.go` (for convenience, there's also a `cros` symlink at the
	top of `tast-tests`). The `Chrome` function here will run directly on the
	test device.

	At the end of the function `testChromeLogin`, add the following code:

	```go
	if _, err = cr.NewConn(ctx, "https://www.google.com/"); err != nil {
	s.Error("Failed to open page: ", err)
	}
	```

	Back in your chroot, run `tast` again:

	```sh
	tast -verbose run <test-device-ip> login.Chrome
	```

	This time, the test should additionally open a Google search page.

	Return to the test file and add the following statement at the end of the
	function `testChromeLogin`:

	```go
	s.Error("This is an intentional error")
	```

	If you build and run the test again, you should see it fail.

	## Next steps

	See [Writing Tests] for more information, and explore the
	[tast-tests repository] to see existing tests and related packages. [Codelab #1]
	walks through the creation of a simple test.

	Additional Tast documentation is available in the [tast repository].

	Many resources are available for learning more about Go. Here are a few:

	* [A Tour of Go] - In-browser introduction to Go's core features.
	* [Official Go documentation] - Package documentation, specifications, blog
	posts, and recorded talks.
	* [Go at Google: Language Design in the Service of Software Engineering] -
	High-level overview of Go's features and design philosophy.
	* [Community Learn wiki] - Links to external resources.

	[Writing Tests]: writing_tests.md
	[tast-tests repository]: https://chromium.googlesource.com/chromiumos/platform/tast-tests/
	[Codelab #1]: codelab_1.md
	[tast repository]: https://chromium.googlesource.com/chromiumos/platform/tast/
	[A Tour of Go]: https://tour.golang.org/
	[Official Go documentation]: https://golang.org/doc/
	[Go at Google: Language Design in the Service of Software Engineering]: https://talks.golang.org/2012/splash.article
	[Community Learn wiki]: https://github.com/golang/go/wiki/Learn