config

Documentation

Overview

Package config provides data structures and functions to configure Device Farm testing.

YAML Config

Repositories using the devicefarm tool will provide a devicefarm.yml file in the repository root. The config.New() function parses this config from a file into a config.Config struct:

config, err := config.New("path/to/config.yml")

Here is an annotated example of what a config file should look like:

# Project ARN. This property is REQUIRED.
project_arn: arn:aws:devicefarm:us-west-2:026109802893:project:1124416c-bfb2-4334-817c-e211ecef7dc0

# Device Pool definitions. this block defines three Device Pools:
# samsung_s4, samsung_s5, and everything. The everything pool
# simply includes both the other pools.
#
# This property is REQUIRED, must have at least one pool defined,
# and each pool must have at least one device.
devicepool_definitions:
samsung_s4:
  - (arn=device:D1C28D6B913C479399C0F594E1EBCAE4) Samsung Galaxy S4 (AT&T)
  - (arn=device:33F66BE404B543669978079E905F8637) Samsung Galaxy S4 (Sprint)
  - (arn=device:D45C750161314335924CE0B9B7D2558E) Samsung Galaxy S4 (T-Mobile)

samsung_s5:
  - (arn=device:5CC0164714304CBF81BB7B7C03DFC1A1) Samsung Galaxy S5 (AT&T)
  - (arn=device:18E28478F1D54525A15C2A821B6132FA) Samsung Galaxy S5 (Sprint)
  - (arn=device:5931A012CB1C4E68BD3434DF722ADBC8) Samsung Galaxy S5 (T-Mobile)

everything:
  - +samsung_s4
  - +samsung_s5

# Defaults defines the build config that will be used for all branches,
# unless overrides are specified in the branches section.
#
# This property is OPTIONAL, but building will fail on a particular branch
# unless a full definition is available for that branch.
defaults:
  # The bash commands to run for this build.
  build:
    - echo "Foo"
    - echo "Bar"

  # The location of APK files, after build commands have been run.
  android:
    apk: ./path/to/build.apk
    apk_instrumentation: ./path/to/instrumentation.apk

  # The device pool name that tests should be run on.
  devicepool: samsung_s4

# Branches defines overrides for particular branches. For each branch,
# it accepts the same properties as `defaults`. Branch configs will be
# merged with `defaults` so that the specified properties override the
# same properties from `defaults`. In this example, only the `devicepools`
# property will be overridden for the `master` branch.
#
# This property is OPTIONAL, but building will fail on a particular branch
# unless a full definition is available for that branch.
branches:
  master:
    devicepool: everything

Index

• func DeviceArns(devices []string) ([]string, error)
• type AndroidConfig
• type BuildManifest
  • func MergeManifests(m1 *BuildManifest, m2 *BuildManifest) *BuildManifest
  • func (manifest *BuildManifest) IsRunnable() (bool, error)
• type Config
  • func New(filename string) (*Config, error)
  • func (config *Config) BranchManifest(branch string) *BuildManifest
  • func (config *Config) FlatDevicePoolDefinitions() (map[string][]string, error)
  • func (config *Config) IsValid() (bool, error)

Functions

func DeviceArns

func DeviceArns(devices []string) ([]string, error)

DeviceArns takes a list of devices from a config file, and returns a list of full ARNs.

Types

type AndroidConfig

type AndroidConfig struct {
	Apk                string `yaml:"apk"`
	ApkInstrumentation string `yaml:"apk_instrumentation"`
}

An AndroidConfig specifies the location of APKs after running the build steps.

type BuildManifest

type BuildManifest struct {
	Steps      []string      `yaml:"build"`
	Android    AndroidConfig `yaml:"android"`
	DevicePool string        `yaml:"devicepool"`
}

A BuildManifest specifies the whole configuration for a build: the steps to perform the build, the location of Android APKs, and the DevicePool names to run on.

func MergeManifests

func MergeManifests(m1 *BuildManifest, m2 *BuildManifest) *BuildManifest

MergeManfiests merges together two BuildManifests, giving the second manifest priority. In other words, any non-blank field in the second manifest will override the value in the first manifest.

func (*BuildManifest) IsRunnable

func (manifest *BuildManifest) IsRunnable() (bool, error)

IsRunnable returns true and nil if the BuildManifest is properly configured to run, and returns false and an error otherwise. For example, if a BuildManifest has no DevicePool, it cannot be run.

type Config

type Config struct {
	ProjectArn            string                   `yaml:"project_arn"`
	DevicePoolDefinitions map[string][]string      `yaml:"devicepool_definitions"`
	Defaults              BuildManifest            `yaml:"defaults"`
	Branches              map[string]BuildManifest `yaml:"branches"`
}

A Config specifies configuration for a particular repo: the names of DevicePools, the default BuildManifest, and override BuildManifests for particular branches.

func New

func New(filename string) (*Config, error)

Creates a new Config from a YAML file.

func (*Config) BranchManifest

func (config *Config) BranchManifest(branch string) *BuildManifest

BranchManifest returns a BuildManifest for the given branch name, by starting from the Defaults manifest (if any) and merging branch-specific overrides on top of it.

func (*Config) FlatDevicePoolDefinitions

func (config *Config) FlatDevicePoolDefinitions() (map[string][]string, error)

FlatDevicePoolDefinitions returns a map of device pool definitions with the "+" references flattened, so that each device pool is just a list of device names. It also sorts each list of device names. It detects circular references or non-existant references and returns an error in those cases.

func (*Config) IsValid

func (config *Config) IsValid() (bool, error)

IsValid returns true and nil if the Config is valid, and returns false and an error otherwise. Valid does not necessesarily mean that all builds will work, it just means that the config does not have any obvious errors.

For example, a config with no `defaults` and no config for the `master` branch could be valid. But if you try to run a build on the `master` branch the build will still fail, because there is no config available.

See also BuildManifest#IsRunnable().