lacros

Documentation

Overview

Package lacros implements a library used to setup and launch lacros-chrome. It also contains some utilities for working with lacros.

Index

• Constants
• Variables
• func CloseLacros(ctx context.Context, l *Lacros)
• func PidsFromPath(ctx context.Context, path string) ([]int, error)
• func WaitForLacrosWindow(ctx context.Context, tconn *chrome.TestConn, title string) error
• type Info
  • func InfoSnapshot(ctx context.Context, tconn *chrome.TestConn) (*Info, error)
• type Lacros
  • func Connect(ctx context.Context, tconn *chrome.TestConn) (l *Lacros, retErr error)
  • func Launch(ctx context.Context, tconn *chrome.TestConn) (*Lacros, error)
  • func LaunchWithURL(ctx context.Context, tconn *chrome.TestConn, url string) (*Lacros, error)
  • func Setup(ctx context.Context, f interface{}, bt browser.Type) (*chrome.Chrome, *Lacros, ash.ConnSource, error)
  • func (l *Lacros) Browser() *browser.Browser
  • func (l *Lacros) Close(ctx context.Context) error
  • func (l *Lacros) CloseResources(ctx context.Context)
  • func (l *Lacros) FindTargets(ctx context.Context, tm chrome.TargetMatcher) ([]*chrome.Target, error)
  • func (l *Lacros) NewConn(ctx context.Context, url string, opts ...cdputil.CreateTargetOption) (*chrome.Conn, error)
  • func (l *Lacros) NewConnForTarget(ctx context.Context, tm chrome.TargetMatcher) (*chrome.Conn, error)
  • func (l *Lacros) StartSystemTracing(ctx context.Context, perfettoConfig []byte) error
  • func (l *Lacros) StartTracing(ctx context.Context, categories []string, opts ...cdputil.TraceOption) error
  • func (l *Lacros) StopTracing(ctx context.Context) (*perfetto_proto.Trace, error)
  • func (l *Lacros) TestAPIConn(ctx context.Context) (*chrome.TestConn, error)
• type Mode
• type Selection

Constants

const UserDataDir = "/home/chronos/user/lacros/"

UserDataDir is the directory that contains the user data of lacros.

Variables

var DeployedBinary = testing.RegisterVarString(
	"lacros.DeployedBinary",
	"",
	"The location of a lacros binary that has been separately deployed to the device. Example: --var=lacros.DeployedBinary=/usr/local/lacros-chrome",
)

DeployedBinary describes the location of a lacros binary that has been separately deployed to the device. For example, /usr/local/lacros-chrome. This is useful to run tests in the Chromium CI with newer version of lacros, or for developers to test against their own local builds of lacros. If this is empty, the lacros described by lacros.Selection is used.

Functions

func CloseLacros

func CloseLacros(ctx context.Context, l *Lacros)

CloseLacros closes the given lacros-chrome, if it is non-nil. Otherwise, it does nothing.

func PidsFromPath

func PidsFromPath(ctx context.Context, path string) ([]int, error)

PidsFromPath returns the pids of all processes with a given path in their command line. This is typically used to find all chrome-related binaries, e.g. chrome, nacl_helper, etc. They typically share a path, even though their binary names differ. There may be a race condition between calling this method and using the pids later. It's possible that one of the processes is killed, and possibly even replaced with a process with the same pid.

func WaitForLacrosWindow

func WaitForLacrosWindow(ctx context.Context, tconn *chrome.TestConn, title string) error

WaitForLacrosWindow waits for a Lacros window to be open and have the title to be visible if it is specified as a param.

Types

type Info

type Info struct {
	// True iff lacros is running.  Note that this information is a snapshot at a
	// particular time. That is, even if the info says lacros is running, it
	// doesn't necessarily mean lacros is still running at any particular time.
	Running bool `json:"isRunning"`
	// True iff lacros has keep-alive enabled..  Note that this information is a
	// snapshot at a particular time.
	KeepAlive bool `json:"isKeepAlive"`
	// Contains the path to the lacros directory - this is where lacros will be
	// executed from. Note that this may change over time if omaha is used (even
	// during a test). This also may be empty is lacros is not running.
	LacrosPath string `json:"lacrosPath"`
}

Info represents the format returned from autotestPrivate.getLacrosInfo.

func InfoSnapshot

func InfoSnapshot(ctx context.Context, tconn *chrome.TestConn) (*Info, error)

InfoSnapshot gets the current lacros info from ash-chrome. The parameter tconn should be the ash TestConn.

type Lacros

type Lacros struct {
	// contains filtered or unexported fields
}

Lacros contains all state associated with a lacros-chrome instance that has been launched. Must call Close() to release resources.

func Connect

func Connect(ctx context.Context, tconn *chrome.TestConn) (l *Lacros, retErr error)

Connect connects to a running lacros instance (e.g launched by the UI) and returns a Lacros object that can be used to interact with it.

func Launch

func Launch(ctx context.Context, tconn *chrome.TestConn) (*Lacros, error)

Launch launches lacros.

func LaunchWithURL

func LaunchWithURL(ctx context.Context, tconn *chrome.TestConn, url string) (*Lacros, error)

LaunchWithURL launches lacros-chrome and ensures there is one page open with the given URL. Note that this function expects lacros to be closed as a precondition.

func Setup

func Setup(ctx context.Context, f interface{}, bt browser.Type) (*chrome.Chrome, *Lacros, ash.ConnSource, error)

Setup runs lacros-chrome if indicated by the given browser.Type and returns some objects and interfaces useful in tests. If the browser.Type is Lacros, it will return a non-nil Lacros instance or an error. If the browser.Type is Ash it will return a nil Lacros instance. TODO(crbug.com/1315088): Replace f with just the HasChrome interface.

func (*Lacros) Browser

func (l *Lacros) Browser() *browser.Browser

Browser returns a Browser instance.

func (*Lacros) Close

func (l *Lacros) Close(ctx context.Context) error

Close closes all lacros chrome targets and the dev session.

func (*Lacros) CloseResources

func (l *Lacros) CloseResources(ctx context.Context)

CloseResources closes lacros resources without closing targets. TODO(crbug.com/1318180): Instead we may want to change Lacros to use ResetState and Close fn like Chrome, or provide these functions on the Browser().

func (*Lacros) FindTargets

func (l *Lacros) FindTargets(ctx context.Context, tm chrome.TargetMatcher) ([]*chrome.Target, error)

FindTargets returns the info about Targets, which satisfies the given cond condition. This must not be called after Close().

func (*Lacros) NewConn

func (l *Lacros) NewConn(ctx context.Context, url string, opts ...cdputil.CreateTargetOption) (*chrome.Conn, error)

NewConn creates a new Chrome renderer and returns a connection to it. If url is empty, an empty page (about:blank) is opened. Otherwise, the page from the specified URL is opened. You can assume that the page loading has been finished when this function returns. This must not be called after Close().

func (*Lacros) NewConnForTarget

func (l *Lacros) NewConnForTarget(ctx context.Context, tm chrome.TargetMatcher) (*chrome.Conn, error)

NewConnForTarget iterates through all available targets and returns a connection to the first one that is matched by tm. This must not be called after Close().

func (*Lacros) StartSystemTracing

func (l *Lacros) StartSystemTracing(ctx context.Context, perfettoConfig []byte) error

StartSystemTracing starts trace events collection from the system tracing service using the marshaled binary protobuf trace config. Note: StopTracing should be called even if StartTracing returns an error. Sometimes, the request to start tracing reaches the browser process, but there is a timeout while waiting for the reply.

func (*Lacros) StartTracing

func (l *Lacros) StartTracing(ctx context.Context, categories []string, opts ...cdputil.TraceOption) error

StartTracing starts trace events collection for the selected categories. Android categories must be prefixed with "disabled-by-default-android ", e.g. for the gfx category, use "disabled-by-default-android gfx", including the space. This must not be called after Close().

func (*Lacros) StopTracing

func (l *Lacros) StopTracing(ctx context.Context) (*perfetto_proto.Trace, error)

StopTracing stops trace collection and returns the collected trace events. This must not be called after Close().

func (*Lacros) TestAPIConn

func (l *Lacros) TestAPIConn(ctx context.Context) (*chrome.TestConn, error)

TestAPIConn returns a new chrome.TestConn instance for the lacros browser. This must not be called after Close().

type Mode

type Mode string

Mode describes whether Lacros is enabled as a primary browser or else.

const (
	LacrosSideBySide Mode = "LacrosSideBySide"
	LacrosPrimary    Mode = "LacrosPrimary"
	LacrosOnly       Mode = "LacrosOnly"
	NotSpecified     Mode = "NotSpecified"
)

Valid values for Mode.

type Selection

type Selection string

Selection describes how lacros-chrome should be set-up during the test. See the Selection constants for more explanation. Use Rootfs as a default. Note that if the lacrosDeployedBinary var is specified, the lacros binary located at the path specified by that var will be used in all cases.

const (
	// Rootfs is used to force the rootfs version of lacros-chrome. No external data dependency is needed.
	// For tests that don't care which lacros they are using, use this as a default.
	Rootfs Selection = "Rootfs"
	// Omaha is used to get the lacros binary.
	Omaha Selection = "Omaha"
	// NotSelected is used for tests that don't need to specify what lacros to select. eg, AutoUpdate that verifies the selection logic itself.
	NotSelected Selection = "NotSelected"
)