Client API

Allocate workspaces through the broker, possibly with more attributes set in the allocation profile. Note that any wanted external tool must be requested in the allocation profile:

from ave.broker import Broker

broker = Broker()
workspace = broker.get({'type':'workspace'})

The profile details are used by the broker to find a lab machine that supports various lab features that may not be globally available. E.g. access to a WLAN that implements a specific encryption standard. This is currently not used much but the functionality is there. Contact the AVE governance board if you want to make use of the feature.

Git

download_git(src, refspec, dst=None, timeout=0, depth=1)

Synchronize a destination tree with a source tree, then check out the commit designated by ‘refspec’. It is safe to use this method to repeatedly synchronize a source into the same destination, using different reference specifications each time.

Execution details:
  • If dst is None or an empty directory: Clone the git, fetch (if needed) and check out the commit.
  • If ‘dst’ is a non-empty git tree: Fetch or pull the refspec (if needed), then check out the commit.
Parameters:
  • src – The source git. May be a local git tree or a remote git URL.
  • refspec – The refspec to check out. Must be a branch name or an SHA1 commit id.
  • dst – The destination directory. May be an None, an empty or non-existing directory or a non-dirty git tree. If None, destination is git/<basename of src under the workspace base directory.
  • timeout – Seconds before time out.
Depth :

Create a shallow clone with a history truncated to the specified number of revisions.

Returns:

The destination path.

Raises:
  • Timeout – If the call took longer than ‘timeout’ seconds.
  • Exception – If the destination tree is dirty or another error occured.
has_git(path, refspec)

Check if the directory on ‘path’ is a git tree that has the commit specified by ‘refspec’.

Note

The identity of the tree itself is not checked in any way (unless refspec is unique enough to establish the identity of the tree).

Parameters:
  • path – The path of the directory to check.
  • refspec – The refspec of interest.
Returns:

True or False.

delete_git(path)

Delete a git tree.

Parameters:path – The path to the git tree. Must be below the root directory of the workspace. May be relative or absolute.
Raises Exception:
 If an error occured.
make_git(path)

Create an empty git tree on ‘path’. The directory will be created as needed. The directory must be located below the base directory of the workspace.

Parameters:path – The path where the git is created.
Returns:Full path to the created git.
Raises Exception:
 If an error occured.

Jenkins

download_jenkins(job_id, build_id=None, artifacts=None, dst=None, timeout=0, base=None)

Download artifacts from a Jenkins job into the workspace.

Parameters:
  • job_id – The Jenkins job ID to download from.
  • build_id – May be used to select a specific build. If None, the last successful build will be downloaded.
  • artifacts – May be used to select specific artifacts to download. If None, all found artifacts will be downloaded. Must be a list of strings or None.
  • dst – The download destination directory. If None, destination is <workspace path>/jenkins/<job_id>/<build_id>.
  • timeout – Seconds before time out.
  • base – May be used to specify the Jenkins URL. If None, the URL will be loaded from the workspace configuration file.
Returns:

The full destination path.

Raises:
  • Timeout – If such occured.
  • Exception – On other errors.

Zip File

validate_zip_file(filename, crc_check=False)

Validates if zip file is corrupt or not.

Parameters:filename – The zip file name.
Crc_check :Switch whether crc check shall be performed, Default to False.
Returns:True or False.
zip(path, dst=None)

Creat a zip archive.

Parameters:
  • path – The dir or file used for zip. It can be a string path or a list of string path.
  • dst – If set, zip archive name is dst, else creat a default automatically.
Returns:

Zip archive name path.

unzip(self, zip_file, path=None, pwd=None)

Unzip a zipfile to a dirrectory.

Parameters:
  • zip_file – The name of zip file for unzip.
  • path – Path specifies a different directory to extract to.
  • pwd – Pwd is the password used for encrypted files.
Returns:

Unzip directory path.

Flocker

flocker_push_file(src, dst=None, key=None)

Upload a file to Flocker. An existing session may be targeted by setting key. This should only be used when uploading from multiple workspaces that are used from the same job.

Parameters:
  • src – Path to the file to upload. The path must point inside the root directory of the workspace.
  • dst – Path to use on the remote server. It may include forward slashes to create a directory hiearchy. If dst is not set, the basename of the uploaded file will be used.
  • key – A valid session key (a string). If not set, the key will be either generated automatically (to start a new session) or set to the key for a session that is already created for this workspace. Normally key is never set, unless the user has created multiple workspaces from the same job.
Returns:

A dictionary containing some metadata about the server-side session.

Note

The key field in the returned metadata may be used as the value of key in calls to flocker_push_file() and flocker_push_string().

flocker_initial(existing_key=None, custom_key=None)
Parameters:
  • existing_key – A valid session key to reuse the session.
  • custom_key – A friendly name (a string). If this parameter is set, the session will hold the session key in the form of <friendly-name>_<hash id>.

Note

Users cannot set existing_key and custom_key at the same time.

flocker_push_string(string, dst, key=None)

Upload a string to Flocker and store it in a file. An existing session may be targeted by setting key.

Parameters:
  • string – A message to store on the server.
  • dst – Path to use on the remote server. It may include forward slashes to create a directory hiearchy.
  • key – A valid session key (a string). If not set, the key will be either generated automatically (to start a new session) or set to the key for a session that is already created for this workspace. Normally key is never set, unless the user has created multiple workspaces from the same job.
Returns:

A dictionary containing some metadata about the server-side session.

Note

The key field in the returned metadata may be used as the value of key in calls to flocker_push_file() and flocker_push_string().

flocker_set_metadata(key=None, contact=None, asset=None, comment=None)

Set extended metadata attributes on the server session.

Parameters:
  • key – A valid session key (a string). If not set, the key will be either generated automatically (to start a new session) or set to the key for a session that is already created for this workspace. Normally key is never set, unless the user has created multiple workspaces from the same job.
  • contact – A string containing contact information. E.g. an email address.
  • asset – A string containing a resource locator. E.g. a tag with context dependent semantics, a URL, or some other globally unique identifier.
  • comment – A free form message string.
Returns:

The updated session metadata.

Note

The key field in the returned metadata may be used as the value of key in calls to flocker_push_file() and flocker_push_string().

Profiling

convert_hprof(infile, outfile)

Convert a HPROF file generated with Handset.dumpheap( native=False ) to a standard format so the file can viewed in a common profiling tool. This method uses hprof-conv.

Note

This is NOT applicable on native heaps.

Parameters:
  • infile – Full path to the file to convert.
  • outfile – Full path where the converted file will be saved.
Raises Excpetion:
 

If an error occured.

Temporary Files

make_tempdir()

Create a directory with a randomized name within the workspace.

Returns:The path to the created directory.
make_tempfile(path=None)

Create a tempfile.

Parameters:path – If path is set the tempfile will be created at path, else it will be created in the workspace root directory.
Returns:The path to the created file.
write_tempfile(sequence, encoding='uft-8')

Create a temp file in workspace and write a sequence of strings to it. The sequence can be any iterable object producing strings, typically a list of strings.

Parameters:
  • sequence – an iterable sequence of strings.
  • encoding – default encoding is utf-8
Returns:

The path to the created file.

Raises Exception:
 

If it was not possible to write the file.

promote(source_path, target, server='flocker')

Promotes a file by making it traceable, this needs to be done to tmp-files that are generated by workspace.makefile() as they are not pushable to the handset. Traceability is secured by pushing the file to flocker and returning the metadata as well as making a symlink to the promoted file named as the target

Parameters:
  • source_path – full path to the source file.
  • target – path inside the ws to the target file.
  • server – server, optional, defaults to flocker.
Returns:

the result of the file storage operation.

File Manipulation

Generic file manipulation and AVE’s golden cage model do not mix easily. The methods listed here are designed to satisfy specific needs that many test jobs do have and that do not break the model.

get_checksum(path)

Get checksum of the file.

Parameters:path – The file to check.
Returns:Checksum value of the file.
Raises Exception:
 If it was not possible to get the checksum.
cat(path, encoding=None, errors=None)

Get the content of the file.

Parameters:
  • path – The file to read.
  • encoding – name of unicode encoding, see python __builtin__.unicode for further information.
  • errors

    specify encoding error handling for invalid characters, see python __builtin__.unicode for further information. Valid values:

    'strict', 'ignore', 'replace'
    
Returns:

the content of the file.

Raises Exception:
 

If it was not possible to read the file.

ls(path, globstr='*')

Return a list of paths matching a pathname pattern.

Parameters:
  • path – String containing a path specification.
  • globstr – String containing a pattern with shell-style wildcards.
Raises Excpetion:
 

If an error occured.

path_exists(path, file_type=None)

Check if path exists in workspace. Optional: check file type of path.

Parameters:
  • path – Path on handset to check.
  • file_type

    If given, verify that the file type of path is file_type. Valid values:

    'symlink', 'directory', 'file'
    
Returns:

True if path exists (and file type is file_type, if that parameter was given), else False.

Raises Exception:
 

If an error occurs.

APK Inspection

get_package_name(path)

Get the package name from the apk (using aapt).

Parameters:path – The path to the apk.
Returns:The package name.
Raises Exception:
 If failed to get package name or an error occured.
get_apk_version(apk_path)

Get the version code of the apk file.

Parameters:apk_path – The apk file to check.
Returns:Version code of the apk file.
Raises Exception:
 If it was not possible to get the version code.

Miscellaneous

get_profile()

Get the profile of the workspace. This dictionary should be used by test jobs to look up properties of the workspace.

get_path()

Get the base directory of this workspace.

get_wifi_ssid()

Get wifi ssid from workspace profile.

get_wifi_pw()

Get wifi password from workspace profile.

delete()

Delete the directory that holds the workspace’s persistent storage. The workspace is no longer usable afterwards.

Raises Exception:
 If an error occured.

External Tools

Workspaces can be used to call external tools. The list of tools that can be called is controlled by a white-list which is configured by the lab owner.

The support for external tools is an explicit loophole to escapce AVE’s golden cage model. This is sometimes needed in special lab environments. Jobs that use such exceptions will not run in DUST which does not white-list any extra tools.

has_tool(tool)

Check whether the given tool is listed in the workspace’s configuration.

Parameters:tool – The tool of interest.
Returns:True or False.
run(cmd, timeout=0)

Run a command line tool on the host of the workspace.

Note

The tool must be listed in the workspace’s configuration file (.ave/config/workspace.json).

Parameters:
  • cmd – The command line to execute. May be a string or a list of strings.
  • timeout – Seconds before a time out.
Returns:

A 3-tuple with: (exit code, output, ‘’)

Note

error messages will end up in “output”.

Raises:
  • Timeout – If such occured.
  • Exception – If the tool is not available in this workspace, execution failed or another error occured.

Table Of Contents

Previous topic

Workspaces

Next topic

System API

This Page