Python API Reference

Complete reference for the ControlFloor Python client library. Over 200 functions organized by category.

Quick Start

The ControlFloor Python library connects to a running ControlFloor Server via WebSocket and provides a high-level API for device interaction. Here's a complete automation script:

from controlfloor import CFConnect # Connect to the server conn = CFConnect("wss://controlfloor.local:8080/ws") conn.login("admin", "password") # Get a device handle device = conn.getDevice("iPhone-12-Pro") # Launch an app device.launchApplication("com.apple.mobilesafari") # Wait for the URL bar and type a URL url_bar = device.getElement(elementIds=["URL"]) url_bar.tap() device.typeText("https://example.com") # Take a screenshot screenshot = device.getScreenshot(format="png") # Check a pixel color pixel = device.getPixelAtPoint(x=100, y=200) print("Done!")

Connection & Setup

Functions for connecting to the ControlFloor server and managing sessions.

cfconnect(ws_url, cookie_string=None, self_signed=False)

Establish a WebSocket connection to the ControlFloor server.

from controlfloor.core import cfconnect conn = cfconnect("wss://server:8080/ws", self_signed=True)

claimExclusiveAccess(message)

Claim exclusive access to the device, preventing other users from interacting with it.

device.claimExclusiveAccess("Running automated tests")

releaseExclusiveAccess()

Release exclusive access to the device.

interruptExclusiveAccess()

Interrupt another user's exclusive access (requires admin privileges).

setDelay(d) / pushDelay(d) / popDelay()

Control the delay between commands. push/pop maintain a stack for nested changes.

setTimeout(d) / pushTimeout(d) / popTimeout()

Control the response timeout for commands.

log_traffic(enable=True)

Enable or disable verbose logging of WebSocket traffic for debugging.

Device Information

getDeviceName()

Returns the user-facing name of the device.

getDeviceStatus()

Returns current device status including connection state and agent health.

getDeviceInformation()

Returns detailed device information (model, iOS version, UDID, etc.).

getCFAgentDeviceInformation()

Returns device information as reported by the CFA Agent on the device.

getCFAgentCapabilities()

Returns the capabilities supported by the running CFA Agent version.

getDeviceOrientation()

Returns the current physical device orientation.

getInterfaceOrientation()

Returns the current UI interface orientation.

getWindowSize()

Returns the current window size in logical points.

getInternetStatus()

Check if the device has internet connectivity.

getNetworkInterfaces()

Returns information about active network interfaces.

getWifiIP()

Returns the device's Wi-Fi IP address.

Application Management

launchApplication(bundleId, relaunch=False)

Launch an app by bundle ID. Set relaunch=True to kill and restart if already running.

device.launchApplication("com.apple.mobilesafari") device.launchApplication("com.example.app", relaunch=True)

killApplication(bundleId)

Terminate a running application.

relaunchApplication(bundleId)

Kill and relaunch an application in one call.

backgroundApplication(bundleId, processId=0)

Send an app to the background without terminating it.

getActiveApplication()

Returns information about the currently foreground application.

getApplicationStack()

Returns the current application stack (foreground + background apps).

getInstalledApplications()

Returns a list of all installed applications on the device.

getApplicationInformation(bundleId)

Returns detailed information about a specific installed app.

getProcessList()

Returns a list of running processes on the device.

Taps & Gestures

All tap and gesture functions accept element search parameters for targeting specific UI elements, or x/y coordinates for absolute positioning.

tap(elementIds, x, y, duration=0, pressure=0, ...)

Tap on an element or at coordinates.

# Tap by element label device.tap(elementIds=["Sign In"]) # Tap at coordinates device.tap(x=200, y=400, useCoordinates=True) # Long press (tap with duration) device.tap(elementIds=["Photo"], duration=2.0)

doubleTap(elementIds, x, y, ...)

Double-tap on an element or at coordinates.

tripleTap(elementIds, x, y, ...)

Triple-tap on an element or at coordinates.

tapAndHold(elementIds, x, y, ...)

Tap and hold on an element (standard press-and-hold gesture).

tapFirm(elementIds, x, y, ...)

Firm press (force touch / haptic touch) on an element.

click(elementIds, x, y, ...) / doubleClick(...)

Click or double-click. Equivalent to tap but uses click semantics.

swipeUp / swipeDown / swipeLeft / swipeRight(elementIds, ...)

Swipe in a direction from an element or coordinates. Configurable width and height.

# Swipe up on a scrollable area device.swipeUp(elementIds=["scrollView"]) # Swipe from center of screen device.centerSwipeLeft()

centerSwipeUp / Down / Left / Right()

Swipe from the center of the screen in any direction.

edgeSwipeUp / Down / Left / Right()

Swipe from the edge of the screen (e.g., to open Control Center or go back).

mouseDown(elementIds, ...) / mouseUp(elementIds, ...)

Simulate mouse down and up events for drag operations.

multiTouchGesture(paths)

Execute a custom multi-touch gesture with multiple finger paths.

swipe(path)

Execute a custom swipe along a defined path.

showControlCenter()

Open the Control Center overlay.

openURL(url)

Open a URL on the device (launches the default browser or deep-links into apps).

Element Discovery & Inspection

Functions for finding and inspecting UI elements in the accessibility tree. Element search parameters are shared across most functions:

  • elementIds — List of accessibility identifiers or labels to match
  • elementTypes — List of element types to filter (e.g., "button", "textField")
  • caseInsensitive — Case-insensitive matching (default: false)
  • timeout — Max time to wait for element to appear
  • maxDepth — Maximum depth of the element tree to search
  • namedOnly — Only return elements with accessibility labels

getElement(elementIds, elementTypes, ...)

Find a single element matching the search criteria.

# Find by label el = device.getElement(elementIds=["Username"]) # Find by type el = device.getElement(elementTypes=["textField"]) # Find with timeout el = device.getElement(elementIds=["Welcome"], timeout=10)

getElements(elementIds, elementTypes, ...)

Find all elements matching the criteria. Supports spatial filters.

getNamedElements(elementIds, elementTypes, ...)

Find all elements that have accessibility labels.

getNamedInputElements(...)

Find all named input elements (text fields, text views).

getButtons(...) / getInputElements(...) / getInteractiveElements(...)

Find elements of specific types.

getSwitches(...) / getSystemSwitches(...) / getSystemButtons(...)

Find switch and button elements.

getKeys(...) / getKeyboards(...)

Find keyboard keys and keyboard elements.

getElementAtPoint(x, y, ...)

Get the element at a specific screen coordinate.

getElementsAtPoints(points, ...)

Get elements at multiple screen coordinates in one call.

getElementsAlongLine(x1, y1, x2, y2, step, ...)

Get elements along a line between two points, sampling at the given step interval.

getElementWithKeyboardFocus(...)

Get the element that currently has keyboard focus.

getScrollRegion(...)

Get the scrollable region for an element.

getApplicationStructure(...) / getLiveApplicationStructure(...)

Get the full element tree for the current application.

getSystemApplicationStructure(...)

Get the element tree for system UI elements (status bar, alerts, etc.).

searchForNamedElements(elementTypes, ...)

Search for named elements across the entire element tree.

searchForElementDepth(...)

Search for the depth at which an element exists in the hierarchy.

Text Input & Keyboard

typeText(text)

Type text using XCTest's built-in text input. Works on the currently focused element.

device.typeText("Hello, World!")

tapText(text)

Type text by tapping individual keys using pre-mapped keyboard layouts. This is the recommended method for secure fields and reliable input across all locales.

# Works in secure/password fields device.tapText("MyP@ssw0rd123")

secureTapText(text)

Type text using tap-based input specifically optimized for secure text fields.

secureTypeText(text)

Type text into secure fields using XCTest's type method.

broadcastText(text)

Broadcast text input to the device.

clearCurrentElementText()

Clear the text in the currently focused text field.

backspace()

Press the backspace key.

typeSpecialKey(key)

Type a special key (Enter, Tab, Escape, etc.).

siri(text)

Activate Siri and speak the given text.

getInstalledKeyboards()

Get a list of keyboards installed on the device.

Switch Controls

enableSwitch(elementIds, ...)

Enable (turn on) a toggle switch.

device.enableSwitch(elementIds=["Wi-Fi"])

disableSwitch(elementIds, ...)

Disable (turn off) a toggle switch.

toggleSwitch(elementIds, ...)

Toggle a switch to the opposite state.

Screenshots & Video

getScreenshot(format="png", jpegQuality=80, ...)

Capture a screenshot of the device screen.

# PNG screenshot img = device.getScreenshot(format="png") # Compressed JPEG img = device.getScreenshot(format="jpeg", jpegQuality=60) # Full resolution img = device.getFullResolutionScreenshot()

getFullResolutionScreenshot(format, ...)

Capture a full-resolution screenshot (native device resolution).

startVideo(clientWidthPortrait, clientHeightPortrait, ...)

Start video streaming from the device.

stopVideo()

Stop video streaming.

getVideoSize() / getVideoStreamStatus() / getVideoStreamConfiguration()

Query video streaming state and configuration.

Pixel Analysis

getPixelAtPoint(x, y, format="hex", ...)

Get the color of a single pixel at the given coordinates.

color = device.getPixelAtPoint(x=100, y=200) # Returns color value at that point

getPixelsAtPoints(points, ...)

Get pixel colors at multiple points in one call.

getPixelsInRegion(x, y, width, height, ...)

Get all pixel colors in a rectangular region.

getPixelsInRegions(regions, ...)

Get pixel colors for multiple regions in one call.

getColorCountForRegion(x, y, width, height, ...)

Get a count of distinct colors in a region.

getHistogramForRegion(x, y, width, height, ...)

Get a color histogram for a region.

File Operations

startFileDownload(url, destination, filename, ...)

Download a file from a URL to the device.

device.startFileDownload( url="https://example.com/data.json", destination="Documents", filename="data.json" )

startFileUpload(data, destination, filename, ...)

Upload file data to the device.

startMediaDownload(url, ...) / startMediaUpload(data, ...)

Download or upload media files (camera roll).

getFileList(path)

List files in a directory on the device.

getFileContents(path)

Read the contents of a file on the device.

getDownloadFolder() / selectDownloadFolder()

Get or set the active download folder on the device.

cancelFileDownload(url, transferId) / cancelFileUpload(transferId)

Cancel an in-progress transfer.

cancelAllFileDownloads() / cancelAllFileUploads()

Cancel all in-progress transfers.

Convenience Commands

High-level file operations available as standalone commands:

from controlfloor.commands import ( clear_camera_roll, download_files, download_to_camera_roll, get_clipboard, load_clipboard, move_downloaded_media_to_camera_roll ) # Clear the camera roll clear_camera_roll() # Download files by URL download_files(["https://example.com/photo.jpg"]) # Get clipboard contents text = get_clipboard() # Set clipboard contents load_clipboard("Text to copy")

Audio Streaming

startAudio(encoding, silence)

Start audio streaming from the device.

stopAudio()

Stop audio streaming.

setAudioStreamConfiguration(encoding, silence)

Configure audio stream settings.

System Controls

home() / simulateHomeButton()

Press the home button (or equivalent gesture on Face ID devices).

lock() / simulateLockButton()

Press the lock/power button.

volumeUp() / volumeDown()

Press volume up or down.

setDeviceOrientation(orientation)

Set the device orientation (portrait, landscape left/right, upside down).

iohid(page, usage)

Send a raw IOHIDEvent to the device for low-level input simulation.

handleAlerts()

Automatically handle system alerts (permission dialogs, etc.).

getAlert()

Get information about the current system alert, if any.

initDevice()

Run device initialization (configure settings for automation).

ping()

Ping the CFA Agent to check connectivity.

benchmark()

Run a performance benchmark on the device.

Configuration & Licensing

licenseDevice()

Apply the license to the current device.

getLicenseGrant() / getLicenseGrantRequest()

Get the current license grant or request a new one.

getCFAgentConfiguration(excludeKeyboard=False)

Get the current CFA Agent configuration.

clearCFAgentConfiguration()

Reset the CFA Agent configuration to defaults.

inspectDevice(keyboardValidation, ...)

Run device inspection to validate keyboard layouts and settings.