uiauto

package
v0.0.0-...-683b059 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2022 License: BSD-3-Clause Imports: 34 Imported by: 0

Documentation

Overview

Package uiauto enables automating with the ChromeOS UI through the chrome.automation API. The chrome.automation API is documented here: https://developer.chrome.com/extensions/automation

Index

Constants

View Source 
const NodeInfoJSFunc = `` /* 380-byte string literal not displayed */

NodeInfoJSFunc is a string of JavaScript code defining a function getNodeInfo. getNodeInfo returns an object in the shape of NodeInfo.

Variables

View Source 
var ErrNodeAppeared = errors.New("node appeared when it should not")

ErrNodeAppeared is returned if node is expected not to be visible

View Source 
var ScreenRecordStopButton = nodewith.Name("Stop screen recording").Role(role.Button)

ScreenRecordStopButton is the button to stop recording the screen.

Functions

func LogRootDebugInfo 

func LogRootDebugInfo(ctx context.Context, tconn *chrome.TestConn, filename string) error

LogRootDebugInfo logs the chrome.automation root debug info to a file.

func RecordOnSuccess 

func RecordOnSuccess() func(*videoConfig)

RecordOnSuccess ensures that we record video even if the test succeeds.

func RecordScreen 

func RecordScreen(ctx context.Context, s testingState, tconn *chrome.TestConn, f func())

RecordScreen records the screen for the duration of the function into recording.webm. For example, if you wanted to record your whole test, you would do the following: 

func MyTest(ctx context.Context, s *testing.State) {
  cr := s.PreValue().(pre.PreData).Chrome
  tconn := s.PreValue().(pre.PreData).TestAPIConn
  uiauto.RecordScreen(ctx, s, tconn, func() {
  <all your existing test code here>
  })
}

func RecordVNCVideo 

func RecordVNCVideo(ctx context.Context, s testingState, mods ...func(*videoConfig)) (stopRecording func())

RecordVNCVideo starts recording video from a VNC stream. It returns a function that will stop recording the video. Example usage: stopRecording := RecordVNCVideo(ctx, s, RecordingFramerate(5)) defer stopRecording()

func RecordVNCVideoCritical 

func RecordVNCVideoCritical(ctx context.Context, s testingState, mods ...func(*videoConfig)) (stopRecording func(), err error)

RecordVNCVideoCritical starts recording video from a VNC stream. If the recording was unable to start, an error will be returned. Otherwise, a function to stop and save the recording will be returned. If the stop recording function fails, it will be logged, but as it is non-critical to the test itself, the test will still pass. Example usage: stopRecording, err := RecordVNCVideoCritical(ctx, s, RecordingFramerate(5)) 

if err != nil {
	handle err
}

defer stopRecording()

func RecordingFileName 

func RecordingFileName(fileName string) func(*videoConfig)

RecordingFileName sets the filename of the video recording (default is recording.webm).

func RecordingFramerate 

func RecordingFramerate(framerate int) func(*videoConfig)

RecordingFramerate sets the framerate of the video recording.

func ReserveForVNCRecordingCleanup 

func ReserveForVNCRecordingCleanup(ctx context.Context) (context.Context, context.CancelFunc)

ReserveForVNCRecordingCleanup shortens the context for vnc video encoding. It calculates the amount of time required to clean up, and calls ctxutil.Shorten by that amount.

func RootDebugInfo 

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

RootDebugInfo returns the chrome.automation root as a string. If the JavaScript fails to execute, an error is returned.

func SaveRecordFromKBOnError 

func SaveRecordFromKBOnError(ctx context.Context, tconn *chrome.TestConn, hasError func() bool, dir string) error

SaveRecordFromKBOnError saves the recording from StartRecordFromKB. This can be used without StopRecordFromKBAndSaveOnError if the screen recording was stopped automatically (i.e. if the screen was locked).

func ScreenRecorderStopSaveRelease 

func ScreenRecorderStopSaveRelease(ctx context.Context, r *ScreenRecorder, fileName string)

ScreenRecorderStopSaveRelease stops, saves and releases the screen recorder.

func StartRecordFromKB 

func StartRecordFromKB(ctx context.Context, tconn *chrome.TestConn, kb *input.KeyboardEventWriter) error

StartRecordFromKB starts screen record from keyboard. It clicks Ctrl+Shift+F5 then select to record the whole desktop. The caller should also call StopRecordFromKB to stop the screen recorder, and save the record file. Here is an example to call this method: 

if err := uiauto.StartRecordFromKB(ctx, tconn, keyboard); err != nil {
    s.Log("Failed to start recording: ", err)
}

defer uiauto.StopRecordFromKBAndSaveOnError(ctx, tconn, s.HasError, s.OutDir())

func StopRecordFromKBAndSaveOnError 

func StopRecordFromKBAndSaveOnError(ctx context.Context, tconn *chrome.TestConn, hasError func() bool, dir string) error

StopRecordFromKBAndSaveOnError stops the record started by StartRecordFromKB. If there is error, it copies the record file to the target dir . It also removes the record file from Downloads for cleanup.

Types

type Action 

type Action = action.Action

Action is a function that takes a context and returns an error.

func Combine 

func Combine(name string, steps ...Action) Action

Combine combines a list of functions from Context to error into one function. Combine adds the name of the operation into the error message to clarify the step. It is recommended to start the name of operations with a verb, e.g., 

"open Downloads and right click a folder"

Then the failure msg would be like: 

"failed to open Downloads and right click a folder on step ..."

func IfSuccessThen 

func IfSuccessThen(preFunc, fn Action) Action

IfSuccessThen returns a function that runs action only if the first function succeeds. The function returns an error only if the preFunc succeeds but action fails, It returns nil in all other situations. Example: 

  dialog := nodewith.Name("Dialog").Role(role.Dialog)
  button := nodewith.Name("Ok").Role(role.Button).Ancestor(dialog)
  ui := uiauto.New(tconn)
  if err := uiauto.IfSuccessThen(ui.WithTimeout(5*time.Second).WaitUntilExists(dialog), ui.LeftClick(button))(ctx); err != nil {
	    ...
  }

func NamedAction 

func NamedAction(name string, fn Action) Action

NamedAction gives a name to an action. It logs when an action starts, and if the action fails, tells you the name of the failing action.

func Repeat 

func Repeat(n int, fn Action) Action

Repeat returns a function that runs the specified function repeatedly for the specific number of times.

func Retry 

func Retry(n int, fn Action) Action

Retry returns a function that retries a given action if it returns error. The action will be executed up to n times, including the first attempt. The last error will be returned. Any other errors will be silently logged.

func RetrySilently 

func RetrySilently(n int, fn Action) Action

RetrySilently returns a function that retries a given action if it returns error. The action will be executed up to n times, including the first attempt. The last error will be returned. Any other errors will be ignored.

func Sleep 

func Sleep(d time.Duration) Action

Sleep returns a function sleeping given time duration.

func UserAction 

func UserAction(name string, fn Action, uc *useractions.UserContext, cfg *useractions.UserActionCfg) Action

UserAction wraps an action with context information. For more details, refer to https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/tast-tests/src/chromiumos/tast/local/chrome/useractions/README.md.

type Context 

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

Context is the context used when interacting with chrome.automation. Each individual UI interaction is limited by the pollOpts such that it will return an error when the pollOpts timeout.

func New 

func New(tconn *chrome.TestConn) *Context

New returns an Context that uses tconn to communicate to chrome.automation. It sets the poll options to the default interval and timeout.

func (*Context) CheckRestriction 

func (ac *Context) CheckRestriction(finder *nodewith.Finder, restriction restriction.Restriction) Action

CheckRestriction returns a function that checks the restriction of the node found by the input finder is as expected. disabled/enabled is a common usecase, e.g, 

CheckRestriction(installButton, restriction.Disabled)
CheckRestriction(installButton, restriction.None)

func (*Context) DoDefault 

func (ac *Context) DoDefault(finder *nodewith.Finder) Action

DoDefault returns a function that calls doDefault() JS method to trigger the default action on a node regardless of its location, e.g. left click on a button. This function can be used when the a11y tree fails to find the accurate location of a node thus mouse.LeftClick() fails consequently.

func (*Context) DoubleClick 

func (ac *Context) DoubleClick(finder *nodewith.Finder) Action

DoubleClick returns a function that double clicks on the location of the node found by the input finder. It will wait until the location is stable before clicking. This returns a function to make it chainable in ui.Run.

func (*Context) EnsureFocused 

func (ac *Context) EnsureFocused(finder *nodewith.Finder) Action

EnsureFocused returns a function that ensures the found node is focused. This can be used to focus on nodes whose state isn't certained. It checks the found node's state and calls FocusAndWait() only if the node is not focused.

func (*Context) EnsureGoneFor 

func (ac *Context) EnsureGoneFor(finder *nodewith.Finder, duration time.Duration) Action

EnsureGoneFor returns a function that check the specified node does not exist for the timeout period. Notice the usage of this function in your code: 1. If you expect an ui-node to go away and not to appear again use WaitUntilGone succeeded with EnsureGoneFor. 2. If you expect an ui-node not to appear at all use EnsureGoneFor.

func (*Context) Exists 

func (ac *Context) Exists(finder *nodewith.Finder) Action

Exists returns a function that returns nil if a node exists. If any node in the chain is not found, it will return an error.

func (*Context) FocusAndWait 

func (ac *Context) FocusAndWait(finder *nodewith.Finder) Action

FocusAndWait returns a function that calls the focus() JS method of the found node. This can be used to scroll to nodes which aren't currently visible, enabling them to be clicked. The focus event is not instant, so an EventWatcher (watcher.go) is used to check its status. The EventWatcher waits the duration of timeout for the event to occur.

func (*Context) Gone 

func (ac *Context) Gone(finder *nodewith.Finder) Action

Gone returns a function that returns nil if a node does not exist. If any node in the chain is not found, it will return nil.

func (*Context) ImmediateDoubleClick 

func (ac *Context) ImmediateDoubleClick(finder *nodewith.Finder) Action

ImmediateDoubleClick returns a function that double clicks on the location of the node found by the input finder. It will not wait until the location is stable before clicking. This returns a function to make it chainable in ui.Run.

func (*Context) ImmediateLeftClick 

func (ac *Context) ImmediateLeftClick(finder *nodewith.Finder) Action

ImmediateLeftClick returns a function that left clicks on the location of the node found by the input finder. It will not wait until the location is stable before clicking. This returns a function to make it chainable in ui.Run.

func (*Context) ImmediateLocation 

func (ac *Context) ImmediateLocation(ctx context.Context, finder *nodewith.Finder) (*coords.Rect, error)

ImmediateLocation returns the location of the node found by the input finder. It will not wait for the location to be stable.

func (*Context) ImmediateRightClick 

func (ac *Context) ImmediateRightClick(finder *nodewith.Finder) Action

ImmediateRightClick returns a function that right clicks on the location of the node found by the input finder. It will not wait until the location is stable before clicking. This returns a function to make it chainable in ui.Run.

func (*Context) Info 

func (ac *Context) Info(ctx context.Context, finder *nodewith.Finder) (*NodeInfo, error)

Info returns the information for the node found by the input finder.

func (*Context) IsNodeFound 

func (ac *Context) IsNodeFound(ctx context.Context, finder *nodewith.Finder) (bool, error)

IsNodeFound immediately checks if any nodes found with given finder. It returns true if found otherwise false.

func (*Context) LeftClick 

func (ac *Context) LeftClick(finder *nodewith.Finder) Action

LeftClick returns a function that left clicks on the location of the node found by the input finder. It will wait until the location is stable before clicking. This returns a function to make it chainable in ui.Run.

func (*Context) LeftClickUntil 

func (ac *Context) LeftClickUntil(finder *nodewith.Finder, condition func(context.Context) error) Action

LeftClickUntil returns a function that repeatedly left clicks the node until the condition returns no error. It will try to click the node once before it checks the condition. This is useful for situations where there is no indication of whether the node is ready to receive clicks. It uses the polling options from the Context.

func (*Context) Location 

func (ac *Context) Location(ctx context.Context, finder *nodewith.Finder) (*coords.Rect, error)

Location returns the location of the node found by the input finder. It will wait until the location is the same for a two iterations of polling.

func (*Context) MakeVisible 

func (ac *Context) MakeVisible(finder *nodewith.Finder) Action

MakeVisible returns a function that calls makeVisible() JS method to make found node visible.

func (*Context) Matches 

func (ac *Context) Matches(ctx context.Context, finder *nodewith.Finder, actual *NodeInfo) (bool, error)

Matches returns whether |finder| matches |actual|. Another way of saying this is "does |finder| map to |actual|?" or "are the properties listed in |finder| present in |actual|?".

func (*Context) MouseClickAtLocation 

func (ac *Context) MouseClickAtLocation(ct clickType, loc coords.Point) Action

MouseClickAtLocation returns a function that clicks on the specified location. This returns a function to make it chainable in ui.Run.

func (*Context) MouseMoveTo 

func (ac *Context) MouseMoveTo(finder *nodewith.Finder, duration time.Duration) Action

MouseMoveTo returns a function moving the mouse to hover on the center point of located node. When duration is 0, it moves instantly to the specified location. Otherwise, the cursor should move linearly during the period. Unlike mouse.Move which is designed to move to a fixed location, this function moves to the target location immediately after getting it, avoid the need of getting it in advance. It addresses the cases that the node only becomes available or changes location in the middle of a sequence of combined steps.

func (*Context) NodesInfo 

func (ac *Context) NodesInfo(ctx context.Context, finder *nodewith.Finder) ([]NodeInfo, error)

NodesInfo returns an array of the information for the nodes found by the input finder. Note that the returning array might not contain any node.

func (*Context) ResetScrollOffset 

func (ac *Context) ResetScrollOffset(finder *nodewith.Finder) Action

ResetScrollOffset returns a function that calls setScrollOffset(0, 0) JS method to reset the scroll offset on a node to scroll it to its default scroll position.

func (*Context) Retry 

func (ac *Context) Retry(n int, fn Action) Action

Retry returns a function that retries a given action if it returns error. The action will be executed up to n times, including the first attempt. The last error will be returned. Any other errors will be silently logged. Between each run of the loop, it will sleep according the the uiauto.Context pollOpts.

func (*Context) RetrySilently 

func (ac *Context) RetrySilently(n int, fn Action) Action

RetrySilently returns a function that retries a given action if it returns error. The action will be executed up to n times, including the first attempt. The last error will be returned. Any other errors will be ignored. Between each run of the loop, it will sleep according the the uiauto.Context pollOpts.

func (*Context) RetryUntil 

func (ac *Context) RetryUntil(action, condition Action) Action

RetryUntil returns a function that repeatedly does the given action until the condition returns no error. It will try to do action once before it checks the condition. It uses the polling options from the Context.

func (*Context) RightClick 

func (ac *Context) RightClick(finder *nodewith.Finder) Action

RightClick returns a function that right clicks on the location of the node found by the input finder. It will wait until the location is stable before clicking. This returns a function to make it chainable in ui.Run.

func (*Context) RightClickUntil 

func (ac *Context) RightClickUntil(finder *nodewith.Finder, condition func(context.Context) error) Action

RightClickUntil returns a function that repeatedly right clicks the node until the condition returns no error. It will try to click the node once before it checks the condition. This is useful for situations where there is no indication of whether the node is ready to receive clicks. It uses the polling options from the Context.

func (*Context) Select 

func (ac *Context) Select(startNodeFinder *nodewith.Finder, startOffset int, endNodeFinder *nodewith.Finder, endOffset int) Action

Select sets the document selection to include everything between the two nodes at the offsets.

func (*Context) WaitForEvent 

func (ac *Context) WaitForEvent(finder *nodewith.Finder, ev event.Event, act Action) Action

WaitForEvent returns a function that conducts the specified action, and then waits for the specified event appears on the specified node. It takes an action as an argument rather than it is a part of a chain of action because it needs to set up a watcher in prior to the action, and also it needs to clean up the allocated resources for the watcher afterwards.

func (*Context) WaitForLocation 

func (ac *Context) WaitForLocation(finder *nodewith.Finder) Action

WaitForLocation returns a function that waits until the node location is stabilized.

func (*Context) WaitUntilExists 

func (ac *Context) WaitUntilExists(finder *nodewith.Finder) Action

WaitUntilExists returns a function that waits until the node found by the input finder exists.

func (*Context) WaitUntilGone 

func (ac *Context) WaitUntilGone(finder *nodewith.Finder) Action

WaitUntilGone returns a function that waits until the node found by the input finder is gone.

func (*Context) WaitUntilNoEvent 

func (ac *Context) WaitUntilNoEvent(finder *nodewith.Finder, ev event.Event) Action

WaitUntilNoEvent returns a function that waits until a specified event has stopped to appear for the specified node.

func (*Context) WithInterval 

func (ac *Context) WithInterval(interval time.Duration) *Context

WithInterval returns a new Context with the specified polling interval.

func (*Context) WithPollOpts 

func (ac *Context) WithPollOpts(pollOpts testing.PollOptions) *Context

WithPollOpts returns a new Context with the specified polling options.

func (*Context) WithTimeout 

func (ac *Context) WithTimeout(timeout time.Duration) *Context

WithTimeout returns a new Context with the specified timeout.

type NodeInfo 

type NodeInfo struct {
	Checked        checked.Checked         `json:"checked,omitempty"`
	ClassName      string                  `json:"className,omitempty"`
	HTMLAttributes map[string]string       `json:"htmlAttributes,omitempty"`
	Location       coords.Rect             `json:"location,omitempty"`
	Name           string                  `json:"name,omitempty"`
	NextSibling    *NodeInfo               `json:"nextSibling,omitempty"`
	Restriction    restriction.Restriction `json:"restriction,omitempty"`
	Role           role.Role               `json:"role,omitempty"`
	State          map[state.State]bool    `json:"state,omitempty"`
	Value          string                  `json:"value,omitempty"`
}

NodeInfo is a mapping of chrome.automation API AutomationNode. It is used to get information about a specific node from JS to Go. NodeInfo intentionally leaves out many properties. If they become needed, add them to the Node struct. As defined in chromium/src/extensions/common/api/automation.idl Exported fields are sorted in alphabetical order.

type ScreenRecorder 

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

ScreenRecorder is a utility to record the screen during a test scenario.

func NewScreenRecorder 

func NewScreenRecorder(ctx context.Context, tconn *chrome.TestConn) (*ScreenRecorder, error)

NewScreenRecorder creates a ScreenRecorder. It only needs to create one ScreenRecorder during one test. It chooses the entire desktop as the media stream. Example: 

  screenRecorder, err := uiauto.NewScreenRecorder(ctx, tconn)
  if err != nil {
		s.Log("Failed to create ScreenRecorder: ", err)
  }

To stop, save, and release the recorder: 

defer uiauto.ScreenRecorderStopSaveRelease(...)

func (*ScreenRecorder) FrameStatus 

func (r *ScreenRecorder) FrameStatus(ctx context.Context) (string, error)

FrameStatus returns the status of the frame being recorded.

func (*ScreenRecorder) Release 

func (r *ScreenRecorder) Release(ctx context.Context)

Release frees the reference to Javascript for this video recorder.

func (*ScreenRecorder) SaveInBytes 

func (r *ScreenRecorder) SaveInBytes(ctx context.Context, filepath string) error

SaveInBytes saves the latest encoded string into a decoded bytes file.

func (*ScreenRecorder) SaveInString 

func (r *ScreenRecorder) SaveInString(ctx context.Context, filepath string) error

SaveInString saves the latest encoded string into a string file.

func (*ScreenRecorder) Start 

func (r *ScreenRecorder) Start(ctx context.Context, tconn *chrome.TestConn) error

Start creates a new media recorder and starts to record the screen. As long as ScreenRecorder is not recording, it can start to record again.

func (*ScreenRecorder) Stop 

func (r *ScreenRecorder) Stop(ctx context.Context) error

Stop ends the screen recording and stores the encoded base64 string.

Source Files

View all Source files

Directories

Path Synopsis
Package browser allows interactions with browser window.
 Package browser allows interactions with browser window.
Package capturemode contains helper methods to work with Capture Mode.
 Package capturemode contains helper methods to work with Capture Mode.
Package checked describes tri-state values of a checkbox or radio button.
 Package checked describes tri-state values of a checkbox or radio button.
Package conndiag provides tools and library calls to create and manage an instance of the Connectivity Diagnostics App.
 Package conndiag provides tools and library calls to create and manage an instance of the Connectivity Diagnostics App.
Package crd provides utilities to set up Chrome Remote Desktop.
 Package crd provides utilities to set up Chrome Remote Desktop.
Package cws provides a utility to install apps from the Chrome Web Store.
 Package cws provides a utility to install apps from the Chrome Web Store.
Package diagnosticsapp contains drivers for controlling the ui of diagnostics SWA.
 Package diagnosticsapp contains drivers for controlling the ui of diagnostics SWA.
Package event describes the type of a chrome.automation AutomationEvent.
 Package event describes the type of a chrome.automation AutomationEvent.
Package faillog provides helper functions for dumping UI data on test failures.
 Package faillog provides helper functions for dumping UI data on test failures.
Package filesapp supports controlling the Files App on Chrome OS.
 Package filesapp supports controlling the Files App on Chrome OS.
Package firmwareupdateapp contains drivers for controlling the ui of firmware update SWA.
 Package firmwareupdateapp contains drivers for controlling the ui of firmware update SWA.
Package holdingspace exports methods for interacting with holding space.
 Package holdingspace exports methods for interacting with holding space.
Package imesettings supports managing input methods in OS settings.
 Package imesettings supports managing input methods in OS settings.
Package launcher is used for controlling the launcher directly through the UI.
 Package launcher is used for controlling the launcher directly through the UI.
Package lockscreen is used to get information about the lock screen directly through the UI.
 Package lockscreen is used to get information about the lock screen directly through the UI.
Package mouse injects mouse events via Chrome autotest private API.
 Package mouse injects mouse events via Chrome autotest private API.
Package nodewith is used to generate queries to find chrome.automation nodes.
 Package nodewith is used to generate queries to find chrome.automation nodes.
Package ossettings supports controlling the Settings App on Chrome OS.
 Package ossettings supports controlling the Settings App on Chrome OS.
Package pointer provides utility interfaces to handle pointing devices (i.e.
 Package pointer provides utility interfaces to handle pointing devices (i.e.
Package printmanagementapp contains common functions used in the app.
 Package printmanagementapp contains common functions used in the app.
Package printpreview provides support for controlling Chrome print preview directly through the UI.
 Package printpreview provides support for controlling Chrome print preview directly through the UI.
Package quicksettings is for controlling the Quick Settings directly from the UI.
 Package quicksettings is for controlling the Quick Settings directly from the UI.
Package restriction describes the restriction state of a chrome.automation AutomationNode.
 Package restriction describes the restriction state of a chrome.automation AutomationNode.
Package role describes the purpose of a chrome.automation AutomationNode.
 Package role describes the purpose of a chrome.automation AutomationNode.
Package scanapp supports controlling the Scan App on Chrome OS.
 Package scanapp supports controlling the Scan App on Chrome OS.
Package shimlessrmaapp contains drivers for controlling the ui of Shimless RMA SWA.
 Package shimlessrmaapp contains drivers for controlling the ui of Shimless RMA SWA.
Package state describes characteristics of a chrome.automation AutomationNode.
 Package state describes characteristics of a chrome.automation AutomationNode.
Package taskmanager contains functions related to the task manager.
 Package taskmanager contains functions related to the task manager.
Package touch provides the uiauto actions to control the touchscreen.
 Package touch provides the uiauto actions to control the touchscreen.
Package trackpad provides helper functions to simulate trackpad events.
 Package trackpad provides helper functions to simulate trackpad events.
Package vkb contains shared code to interact with the virtual keyboard.
 Package vkb contains shared code to interact with the virtual keyboard.
Package wmp contains utility functions for window management and performance.
 Package wmp contains utility functions for window management and performance.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.