Skip to main content

Screen API

Provides an API for capturing screenshots and performing screen recordings

screen.capture​

Signatures​

capture()

capture(region)

Description​

Captures current frame and returns userdata object

screen.capture​

Signatures​

capture()

capture(region)

Description​

Capture a screenshot of a specific region on the screen.

Takes a screenshot of only the specified region area instead of the full screen. The region parameter defines the area to capture.

Parameters​

  • region - Region object or table defining the area to capture

Returns a userdata object containing the captured region image.

Example​

local button_region = region.relative(100, 100, 200, 50)
local region_screenshot = screen.capture(button_region)

-- Use the region screenshot for further analysis
local brightness = detect.brightness(region_screenshot)

screen.captureAndEmit​

Signatures​

captureAndEmit(opts \ [])

Description​

Capture a screenshot and emit it as a workflow event.

Takes a screenshot and sends it as an event within the workflow system. This is typically used for debugging or workflow documentation purposes.

Options​

  • stepId - Identifier for the workflow step this capture belongs to
  • type - Type of capture being performed

Returns a userdata object containing the captured image.

Example​

local screenshot = screen.captureAndEmit({
  stepId = "login_step_1",
  type = "before_action"
})

screen.get​

Signatures​

get(name)

Description​

Get's a UI element by name

screen.is​

Signatures​

is(screen_name)

Description​

Check if the current screen matches the specified screen name.

Compares the currently active screen with the provided screen name to determine if they match.

Parameters​

  • screen_name - Name of the screen to check against

Returns true if the current screen matches the specified name, false otherwise.

Example​

local is_home = screen.is("home_screen")

if is_home then
  print("Currently on home screen")
else
  print("Not on home screen")
end

screen.press​

Signatures​

press(name)

Description​

Press a UI element by its name on the current screen.

Locates a UI element by name on the current screen and performs a press action on it. The element must be visible and active on the current screen.

Parameters​

  • name - Name of the UI element to press

Raises an error if the element is not found on the current screen.

Example​

screen.press("login_button")
screen.press("settings_icon")

screen.print​

Signatures​

print(text)

Description​

Display text on the screen overlay.

Renders the specified text directly onto the screen as an overlay. This is useful for debugging or providing visual feedback during automation.

Parameters​

  • text - Text string to display on screen

Example​

screen.print("Starting login process...")
screen.print("Current step: Enter credentials")
screen.print("Test completed successfully")

screen.type​

Signatures​

type()

Description​

Get the type/name of the current active screen.

Returns the name identifier of the currently active screen.

Returns a string representing the current screen's name. Raises an error if there is no active screen.

Example​

local current_screen = screen.type()
print("Current screen: " .. current_screen)

if current_screen == "login_screen" then
  print("User is on login screen")
end