Honeydew

Honeydew is a test framework agnostic device controller written in Python that provides Host-(Fuchsia)Target interaction.

Supported host operating systems:

• Linux

Assumptions:

• This tool was built to be run locally. Remote workflows (i.e. where the Target and Host are not colocated) are in limited support, and have the following assumptions:
  • You use a tool like fssh tunnel or funnel to forward the Target from your local machine to the remote machine over a SSH tunnel
  • Only one device is currently supported over the SSH tunnel.
  • If the device reboots during the test, it may be necessary to re-run the fssh tunnel command manually again in order to re-establish the appropriate port forwards.
• Fastboot CLI is present on the host and is included in $PATH environmental variable (required only if you need to use Fastboot transport).

Contributing

One of Honeydew's primary goals is to make it easy for anyone working on host target interactions to contribute.

Honeydew is meant to be the one stop solution for any Host-(Fuchsia)Target interactions. We can only make this possible when more people contribute to Honeydew and add more and more interactions that others can also benefit.

Getting started

• Use a Linux machine for Honeydew development and testing
• Follow instructions on how to submit contributions to the Fuchsia project for the Gerrit developer work flow

Data dependencies

Honeydew, as packaged by the GN build system, comes bundled with some of its data dependencies. However, if Honeydew is run outside of the build system, or if users wish to override with custom data dependencies, the following environment variables can be specified:

• HONEYDEW_FASTBOOT_OVERRIDE: Absolute path to fastboot binary.

Best Practices

Here are some of the best practices that should be followed while contributing to Honeydew:

• Ensure code is compliant with Honeydew code guidelines by running conformance.sh.
• Ensure there is unit tests and functional tests coverage and that you have run the impacted functional tests (either locally or in infra) to make sure contributions are working.
• If a new unit test module is added,
  • ensure this new test is included in group("tests") section in the BUILD.gn file (located in the same directory as unit test).
  • ensure this new test is included in group("tests") section in the top level Honeydew unit tests BUILD file.
  • ensure instructions specified in unit tests README are sufficient to run this new test locally.
• If a new functional test module is added,
  • ensure instructions specified in functional tests README are sufficient to run this new test locally.
  • ensure this new test is included in group("tests") section in the top level Honeydew functional tests BUILD file.
  • follow how to add a new test to run in infra.
• If contribution involves adding a new host target interaction method or class, you would need to update the interfaces definitions.
• If CL introduces a new affordance, then add yourself as Affordance OWNER.

Honeydew code guidelines

Honeydew is a crowd sourced and community contributed library that is foundational to all Lacewing tests so we have curated a set of guidelines and conformance scripts to ensure its uniformity, functional correctness, and stability.

To learn more, refer to Honeydew code guidelines.

Note - Prior to running this, please make sure to follow Setup

Running cd $FUCHSIA_DIR && sh $FUCHSIA_DIR/src/testing/end_to_end/honeydew/scripts/conformance.sh successfully will ensure you have followed the guidelines. Run this script and fix any errors it suggests.

Once the script has completed successfully, it will print output similar to the following:

INFO: Honeydew code has passed all of the conformance steps

Code Review Expectations

If you are making non-superficial changes to Honeydew, refer to Honeydew's Best Practices for general guidances.

Additionally, please follow Honeydew's CL review process as detailed below:

Author

• On the initial patchset where reviewers will be added, do the following before starting the review:
  1. Ensure conformance.sh passes
  2. Include the following information at the end of the commit message:

  Verified the following on Patchset: <initial patchset number>
  * Honeydew code guidelines
  * Successfully ran the impacted functional tests using [LocalRun|InfraRun]
  

• On final patchset that will be used for merging, do the following before merging the CL:
  1. Ensure conformance.sh passes
  2. Ensure CL does not introduce any regressions by successfully running all of the Honeydew staging builders using try-jobs
  • Look for lacewing-self-staging in the try-job name reg-ex filter field (exclude -subbuild builders).
  • For reference, see screenshot
  3. Update the commit message with the final patchset number:

  Verified the following on Patchset: <final patchset number>
  * Honeydew code guidelines
  * Successfully ran the impacted functional tests using [LocalRun|InfraRun]
  * Successfully ran Honeydew builders using try-jobs
  

Reviewer

• Remind the CL author to follow Best Practices section by opening a comment and asking author to resolve this comment only after they verify on absolute final patchset that will be merged
• Verify the author has included all the information in commit message as mentioned in Author section

Interactive usage

If you like to use Honeydew in an interactive Python terminal refer to interactive usage.