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
• 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) 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.

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"`
	// 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) 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"
)