When the Chrome OS team started using autotest, we tried our best to figure out how to fit our code and our tests into the upstream style with little guidance and poor documentation. This went poorly. With the benefit of hindsight, we’re going to lay out some best-practices that we’d like to enforce going forward. In many cases, there is legacy code that contradicts this style; we should go through and refactor that code to fit these guidelines as time allows. Quick referenceUpstream documentationThere is a sizeable volume of general Autotest documentation available on github:https://github.com/autotest/autotest/wiki Coding styleBasically PEP-8. Significant deviations/additions are discussed in CODING_STYLE at the top level of the autotest repo.Where should my code live?
Writing testsAn autotest is really defined by its control file. A control file contains important metadata about the test (name, author, description, duration, what suite it’s in, etc) and then pulls in and executes the actual test code. This test code can be shared among multiple distinct test cases by parameterizing it and passing those parameters in from separate control files.Autotests must:
Autotests must not:
Autotests may:
Autotest has a notion of both client-side tests and server-side tests. Code in a client-side test runs only on the device under test (DUT), and as such isn’t capable of maintaining state across reboots or handling a failed suspend/resume and the like. If possible, an autotest should be written as a client-side test. A ‘server’ test runs on the autotest server, but gets assigned a DUT just like a client-side test. It can use various autotest primitives (and library code written by the CrOS team) to manipulate that device. Most, if not all, tests that use Servo or remote power management should be server-side tests, as an example. Adding a test involves putting a control file and a properly-written test wrapper in the right place in the source tree. There are conventions that must be followed, and a variety of primitives available for use. When writing any code, whether client-side test, server-side test, or library, have a strong bias towards using autotest utility code. This keeps the codebase consistent. Writing a testThis section explains considerations and requirements for any autotest, whether client or server.Control filesUpstream documentationOur local conventions for autotest control files deviate from the above a bit, but the indication about which fields are mandatory still holds.
Currently existing suites are defined in the test_suites/ subdirectory at the top level of the autotest repo. Read the docstrings there to see if your new test fits into one that’s already defined. Pure pythonLie, cheat and steal to keep your tests in pure python. It will be easier to debug failures, it will be easier to generate meaningful error output, it will be simpler to get your tests installed and run, and it will be simpler for the lab team to build tools that allow you to quickly iterate.Shelling out to existing command-line tools is done fairly often, and isn’t a terrible thing. The test author can wind up having to do a lot of output parsing, which is often brittle, but this can be a decent tradeoff in lieu of having to reimplement large pieces of functionality in python. Note that you will need to be sure that any commands you use are installed on the host. For a client-side test, “the host” means “the DUT”. For a server-side test, “the host” typically means “the system running autoserv”; however, if you use SiteHost.run(), the command will run on the DUT. On the server, your tests will have access to all tools common to both a typical CrOS chroot environment and standard Goobuntu. If you want to use a tool on the DUT, it may be appropriate to include it as a dependency of the chromeos-base/chromeos-test package. This ensures that the tool is pre-installed on every test image for every device, and will always be available for use. Otherwise, the tool must be installed as an autotest “dep”. Never install your own shell scripts and call them. Anything you can do in shell, you can do in python. Reporting failuresAutotest supports several kinds of failure statuses:
Considerations when writing client-side testsAll client-side tests authored at Google must live in the client/site_tests sub-directory of the autotest source tree.Compiling and executing binariesIt is possible to compile source that’s included with your test and use the products at test runtime. The build infrastructure will compile this code for the appropriate target architecture and package it up along with the rest of your test’s resources, but this increases your development iteration time as you need to actually re-build and re-package your test to deploy it to the device. While we hope to improve tooling support for this use case in the future, avoiding this issue is the ideal.If you can’t avoid this, here’s how to get your code compiled and installed as a part of your test:
Reusing code (“fixtures”)Any autotest is, essentially, a single usage of a re-usable test fixture. This is because run_once() in your test wrapper can take any arguments you want. As such, multiple control files can re-use the same wrapper -- and should, where it makes sense.Considerations when writing server-side testsAll server-side tests authored at Google must live in the server/site_tests sub-directory of the autotest source tree.It should be even easier to keep the server-side of a test in pure python, as you should simply be driving the DUT and verifying state. When/why to write a server-side testserver-side tests are appropriate when technical limitations preclude executing important operations of the test from the DUT. The prototypical example is rebooting the DUT. Other examples include tests that manipulate the network around the DUT (e.g. WiFi tests), tests that power off the DUT, and tests that rely on a Servo attached to the DUT.One simple criterion for whether to write a server-side test is this: Is the DUT an object that the test must manipulate? If the answer is “yes”, then a server-side test makes sense. Control files for server-side testsServer-side tests commonly operate on the DUT as an object, which means that it’s usually necessary for that object to be constructed and passed to the test from the control file. Creating the host object in the control file can be done using certain definitions present in the global environment of every control file:
Below is a sample fragment for a control file that runs a simple server side test in parallel on all the hosts specified for the test. The fragment is a complete control file, except for the missing boilerplate comments and documentation definitions required in all control files.
Note: The sample above relies on a common convention that the run_once() method of a server-side test defines an argument named host with a default value, e.g.
Operations on Host objectsA Host object supports various methods to operate on a DUT. Below is a short list of important methods supported by instances of Host:
Servo-based testsFor server-side tests that use a servo-attached DUT, the host object has a servo attribute. For servo-attached hosts in the lab, hosts.create_host() automatically creates the servo object and connects it to the associated servod (running on a beaglebone host). So, to write a servo-based test to run it the lab, no special code is needed; the code can just use the host’s host.servo object.However, in general, tests using servo also need to support running from run_remote_tests.sh. In this case, it can be necessary to pass the host and port number of the servod for the test to connect to. That should be done with the following standard boilerplate in the control file:
If the test control file follows the formula above, the test can be reliably called in a variety of ways:
run_remote_tests.sh --servo ... other arguments ...
run_remote_tests.sh --args=”servo_port=...” … run_remote_tests.sh --args=”servo_host=...” … run_remote_tests.sh --args=”servo_host=... servo_port=...” ... Calling client-side tests from a server-side testCommonly, server-side tests need to do more on the DUT than simply run short shell commands. In those cases, a client-side test should be written and invoked from the server-side test. In particular, a client side test allows the client side code to be written in Python that uses standard autotest infrastructure, such as various utility modules or the logging infrastructure.Below is a short snippet showing the standard form for calling a client-side test from server-side code:
Writing library codeThere is a large quantity of Chromium OS specific code in the autotest codebase. Much of this exists to provide re-usable modules that enable tests to talk to system services. The guidelines from above apply here as well. This code should be as pure python as possible, though it is reasonable to shell out to command line tools from time to time. In some cases we’ve done this where we could (now) use the service’s DBus APIs directly. If you’re adding code to allow tests to communicate with your service, it is strongly recommended that you use DBus where possible, instead of munging config files directly or using command-line tools.Currently, our library code lives in a concerning variety of places in the autotest tree. This is due to a poor initial understanding of how to do things, and new code should follow the following conventions instead:
Adding test depsThis does not refer to the optional DEPENDENCIES field in test control files. Rather, this section discusses how and when to use code/data/tools that are not pre-installed on test images, and should (or can) not be included right in with the test source.Unfortunately, there is no hard-and-fast rule here. Generally, if this is some small tool or blob of data you need for a single test, you should include it as discussed above in Writing client-side tests. If you’re writing the tool, and it has use for developers as well as in one or more tests that you’re writing, then make it a first-class CrOS project. Write an ebuild, write unit tests, and then add it to the test image by default. This can be done by RDEPENDing on your new test package from the chromeos-test ebuild. If your code/data falls in the middle (useful to several tests, not to devs), and/or is large (hundreds of megabytes as opposed to tens) then using an autotest ‘dep’ may be the right choice. Conceptually, an autotest test dep is simply another kind of archive that the autotest infrastructure knows how to fetch and unpack. There are two components to including a dependency from an autotest test -- setup during build time and installing it on your DUT when running a test. The setup phase must be run from your tests setup() method like so:
The above gets run when you “build” the test. The other half of this equation is actually installing the dependency so you can use it while running a test. To do this, add the following to either your run_once or initialize methods: dep = dep_name dep_dir = os.path.join(self.autodir, 'deps', dep=dep) self.job.install_pkg(dep, 'dep', dep_dir)You can now reference the content of your dep using dep_dir. Now that you know how to include a dep, the next question is how to write one. Before you read further, you should check out client/deps/* for many examples of deps in our autotest tree. Create a dep from a third-party packageThere are many examples of how to do this in the client/deps directory already. The key component is to check in a tarball of the version of the dependency you’d like to include under client/deps/your_dep.All deps require a control file and an actual python module by the same name. They will also need a copy of common.py to import utils.update_version. Both the control and common are straightforward, the python module does all the magic. The deps python module follows a standard convention: a setup function and a call to utils.update_version. update_version is used instead of directly calling setup as it maintains additional versioning logic ensuring setup is only done 1x per dep. The following is its method signature: def update_version(srcdir, preserve_srcdir, new_version, install, *args, **dargs)Notably, install should be a pointer to your setup function and *args should be filled in with params to said setup function. If you are using a tarball, your setup function should look something like: def setup(tarball, my_dir) utils.extract_tarball_to_dir(tarball, my_dir) os.chdir(my_dir) utils.make() # this assumes your tarball has a Makefile.And you would invoke this with: utils.update_version(os.getcwd(), True, version, setup, tarball_path, os.getcwd())Note: The developer needs to call this because def setup is a function they are defining that can take any number of arguments or install the dep in any way they see fit. The above example uses tarballs but some are distributed as straight source under the src dir so their setup function only takes a top level path. We could avoid this by forcing a convention but that would be artificially constraining the deps mechanism. Once you’ve created the dep, you will also have to add the dep to the autotest-deps package in chromiumos-overlay/chromeos-base/autotest-deps, ‘cros_workon start’ it, and re-emerge it. Create a dep from other chrome-os packages One can also create autotest deps from code that lives in other CrOS packages, or from build products generated by other packages. This is similar as above but you can reference code using the CHROMEOS_ROOT env var that points to the root of the CrOS source checkout, or the SYSROOT env var (which points to /build/<board>) to refer to build products. Again, read the above. Here’s an example of the former with the files I want in chromeos_tree/chromite/my_dep/* where this will be the python code in autotest/files/client/deps/my_dep/my_dep.py module. import common, os, shutilfrom autotest_lib.client.bin import utilsversion = 1def setup(setup_dir): my_dep_dir = os.path.join(os.environ['CHROMEOS_ROOT'], 'chromite', 'buildbot') shutil.copytree(my_dep_dir, setup_dir)work_dir = os.path.join(os.getcwd(), 'src')utils.update_version(os.getcwd(), True, version, setup, work_dir) |
|
Chromium OS > Testing Home >
Autotest Best Practices |