ffctl

package module
v0.0.0-...-f84bc58 Latest Latest
Warning

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

 Go to latest Published: Jan 19, 2026 License: MIT Imports: 17 Imported by: 0

README

ffctl

A high-level API for controlling Firefox over its Marionette protocol.

Protocol coverage

This isn't a super popular protocol to implement, and the docs are not kept up to date. So the best reference for the supported operations is the source code.

✅ = Implemented

❌ = Not planned

[] = TODO

  • ❌ Marionette:AcceptConnections
    Firefox starts accepting connections by default.
  • ❌ Marionette:GetContext
    This crate does not support the "chrome" context.
  • ❌ Marionette:GetScreenOrientation
    This operation is only supported on Android.
  • ❌ Marionette:GetWindowType
    Does not seem useful.
  • ❌ Marionette:Quit
    Drop the Session struct to quit.
  • ❌ Marionette:RegisterChromeHandler
    This crate does not support the "chrome" context.
  • ❌ Marionette:UnregisterChromeHandler
    This crate does not support the "chrome" context.
  • ❌ Marionette:SetContext
    This crate does not support the "chrome" context.
  • ❌ Marionette:SetScreenOrientation
    This operation is only supported on Android.
  • [] Addon:Install
  • [] Addon:Uninstall
  • [] L10n:LocalizeProperty
  • ❌ reftest:setup
  • ❌ reftest:run
  • ❌ reftest:teardown
  • ✅ WebDriver:AcceptAlert
  • ✅ WebDriver:AddCookie
  • ✅ WebDriver:Back
  • ❌ WebDriver:CloseChromeWindow This crate does not support the "chrome" context.
  • ✅ WebDriver:CloseWindow
  • ✅ WebDriver:DeleteAllCookies
  • ✅ WebDriver:DeleteCookie
  • ✅ WebDriver:DeleteSession
  • ✅ WebDriver:DismissAlert
  • ✅ WebDriver:ElementClear
  • ✅ WebDriver:ElementClick
  • ✅ WebDriver:ElementSendKeys
  • ✅ WebDriver:ExecuteAsyncScript
  • ✅ WebDriver:ExecuteScript
  • ✅ WebDriver:FindElement
  • ✅ WebDriver:FindElementFromShadowRoot
  • ✅ WebDriver:FindElements
  • ✅ WebDriver:FindElementsFromShadowRoot
  • ✅ WebDriver:Forward
  • ✅ WebDriver:FullscreenWindow
  • ✅ WebDriver:GetActiveElement
  • ✅ WebDriver:GetAlertText
  • [] WebDriver:GetCapabilities
  • ✅ WebDriver:GetComputedLabel
  • ✅ WebDriver:GetComputedRole
  • ✅ WebDriver:GetCookies
  • ✅ WebDriver:GetCurrentURL
  • ✅ WebDriver:GetElementAttribute
  • ✅ WebDriver:GetElementCSSValue
  • [] WebDriver:GetElementProperty
  • ✅ WebDriver:GetElementRect
  • ✅ WebDriver:GetElementTagName
  • ✅ WebDriver:GetElementText
  • ✅ WebDriver:GetPageSource
  • ✅ WebDriver:GetShadowRoot
  • ✅ WebDriver:GetTimeouts
  • ✅ WebDriver:GetTitle
  • ✅ WebDriver:GetWindowHandle
  • ✅ WebDriver:GetWindowHandles
  • ✅ WebDriver:GetWindowRect
  • ✅ WebDriver:IsElementDisplayed
  • ✅ WebDriver:IsElementEnabled
  • ✅ WebDriver:IsElementSelected
  • ✅ WebDriver:MinimizeWindow
  • ✅ WebDriver:MaximizeWindow
  • ✅ WebDriver:Navigate
  • ✅ WebDriver:NewSession
  • ✅ WebDriver:NewWindow
  • ✅ WebDriver:PerformActions
  • ✅ WebDriver:Print
  • ✅ WebDriver:Refresh
  • ✅ WebDriver:ReleaseActions
  • ✅ WebDriver:SendAlertText
  • [] WebDriver:SetPermission
  • [] WebDriver:SetTimeouts
  • ✅ WebDriver:SetWindowRect
  • ✅ WebDriver:SwitchToFrame
  • ✅ WebDriver:SwitchToParentFrame
  • ✅ WebDriver:SwitchToWindow
  • ✅ WebDriver:TakeScreenshot
  • ❌ GPC:GetGlobalPrivacyControl
  • ❌ GPC:SetGlobalPrivacyControl
  • ❌ WebAuthn:AddVirtualAuthenticator
  • ❌ WebAuthn:RemoveVirtualAuthenticator
  • ❌ WebAuthn:AddCredential
  • ❌ WebAuthn:GetCredentials
  • ❌ WebAuthn:RemoveCredential
  • ❌ WebAuthn:RemoveAllCredentials
  • ❌ WebAuthn:SetUserVerified

Documentation

Overview

Package ffctl implements the clientside of the marionette protocol for programmatically controling the firefox browser.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BoundingBox 

type BoundingBox struct {
	X      float64 `json:"x"`
	Y      float64 `json:"y"`
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}
type Cookie struct {
	Name     string `json:"name"`
	Value    string `json:"value"`
	Domain   string `json:"domain,omitzero"`
	Path     string `json:"path,omitzero"`
	HttpOnly bool   `json:"httpOnly,omitzero"`
	Secure   bool   `json:"secure,omitzero"`
	SameSite string `json:"sameSite,omitzero"`
	// The timestamp the cookie will expire at in seconds
	Expiry uint64 `json:"expiry,omitzero"`
}

A browser cookie

type MarionetteError 

type MarionetteError struct {
	Code       string `json:"error"`
	Message    string `json:"message"`
	Stacktrace string `json:"stacktrace"`
}

func (*MarionetteError) Error 

func (e *MarionetteError) Error() string

type MouseButton 

type MouseButton byte
var (
	MouseButtonLeft  MouseButton = 0
	MouseButtonRight             = 1
)

type PdfExportConfig 

type PdfExportConfig struct {
	Margin     PdfExportMargins        `json:"margin"`
	Dimensions PdfExportPageDimensions `json:"page"`
	// Scale of the webpage rendering.
	Scale float64 `json:"scale"`
	// If `true`, overrides CSS to make the content fit the page size.
	ShrinkToFit bool   `json:"shrinkToFit"`
	Orientation string `json:"orientation"`
	// If `true`, the export will include background colors and images.
	PrintBackground bool `json:"background"`
	// Page ranges to print.
	// Each element should either define a page number (e.g. `3`) or a range of pages (e.g. `1-10`)
	PageRanges []string `json:"pageRanges"`
}

func DefaultPdfExportConfig 

func DefaultPdfExportConfig() PdfExportConfig

Returns default configuration for exporting a page as a pdf

type PdfExportMargins 

type PdfExportMargins struct {
	Top    float64 `json:"top"`
	Bottom float64 `json:"bottom"`
	Left   float64 `json:"left"`
	Right  float64 `json:"right"`
}

type PdfExportPageDimensions 

type PdfExportPageDimensions struct {
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}

type Script 

type Script struct {
	// Arguments to pass to the script.
	//
	// In the script, these are accessible using implicit [arguments object].
	//
	// [arguments object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments
	Args []any
	// contains filtered or unexported fields
}

Javascript code to be executed in the browser.

func (Script) Execute 

func (s Script) Execute() (any, error)

Executes the script in the browser and returns the result.

func (Script) ExecuteAndWaitForCallback 

func (s Script) ExecuteAndWaitForCallback() (any, error)

Executes the script in the browser and returns the result.

A callback is automatically added as the last element of the implicit arguments array to the script. This function returns whatever is passed to the callback.

This lets you call asynchronous javascript functions.

type Session 

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

An instance of the firefox browser being controlled.

A session must not be accessed from multiple goroutines.

func NewGraphicalSession 

func NewGraphicalSession(url string) (Session, error)

Starts a new graphical browser session.

func NewHeadlessSession 

func NewHeadlessSession(url string) (Session, error)

Starts a new headless browser session.

func NewSession 

func NewSession(config SessionConfig) (Session, error)

Starts a new browser session with the given configuration.

Call Session.Close to end it.

func (*Session) AcceptAlert 

func (s *Session) AcceptAlert() error

Accepts a currently displayed alert modal.

func (*Session) AddCookie 

func (s *Session) AddCookie(cookie Cookie) error

Adds a single cookie to the cookie store associated with the current document's address.

The only required fields are [Cookie.Name] and [Cookie.Value].

func (*Session) ClearCookies 

func (s *Session) ClearCookies() error

Deletes all cookies visible to the current document

func (*Session) Close 

func (s *Session) Close()

Ends the firefox browser session and cleans up associated resources.

func (*Session) CloseCurrentTab 

func (s *Session) CloseCurrentTab() error

Close the currently selected tab.

When multiple open tabs are present, the currently selected tab will be closed. Otherwise, the window itself will be closed. If it is the last window open, this function is a no-op to prevent a shutdown of the session.

If a tab or window is closed, the browsing context is switches to one of the remaining open tabs.

func (*Session) DeleteCookie 

func (s *Session) DeleteCookie(name string) error

Deletes the cookie with the given name.

No-op if no such cookie exists.

func (*Session) DismissAlert 

func (s *Session) DismissAlert() error

Dismisses a currently displayed alert modal.

func (*Session) ExportPdf 

func (s *Session) ExportPdf(config PdfExportConfig) ([]byte, error)

Exports the current page as a PDF file.

Returns the raw PDF bytes, ready to be written to a file.

func (*Session) FindElement 

func (s *Session) FindElement(selector string) (WebElement, error)

Returns the first element matching the css selector.

func (*Session) FindElements 

func (s *Session) FindElements(selector string) ([]WebElement, error)

Returns a list of all elements matching the css selector.

func (*Session) FocusTab 

func (s *Session) FocusTab(handle TabHandle) error

Switches focus to the given tab.

func (*Session) Fullscreen 

func (s *Session) Fullscreen() error

Makes the current window full-screen, as if the user agent had done "View > Enter Full Screen".

func (*Session) GetActiveElement 

func (s *Session) GetActiveElement() (WebElement, error)

Returns the currently active element in the document.

func (*Session) GetAlertMessage 

func (s *Session) GetAlertMessage() (string, error)

Returns the message shown in a currently alert modal.

func (*Session) GetAllTabs 

func (s *Session) GetAllTabs() ([]TabHandle, error)

Returns a list of handles to open browser windows & tabs.

func (*Session) GetBoundingBox 

func (s *Session) GetBoundingBox() (BoundingBox, error)

Returns the size and position of the current window.

func (*Session) GetCookies 

func (s *Session) GetCookies() ([]Cookie, error)

Returns all the cookies for the current domain.

This is equivalient to calling `document.cookie` and parsing the result.

func (*Session) GetCurrentTab 

func (s *Session) GetCurrentTab() (TabHandle, error)

Get the current tab's handle.

func (*Session) GetPageSource 

func (s *Session) GetPageSource() (string, error)

Returns a string representation of the DOM

func (*Session) GetTimeouts 

func (s *Session) GetTimeouts() (Timeouts, error)

Returns the timeout values for the current session.

func (*Session) GetTitle 

func (s *Session) GetTitle() (string, error)

/ Returns the title of the current window

func (*Session) GetUrl 

func (s *Session) GetUrl() (string, error)

Returns the current URL

func (*Session) GoBack 

func (s *Session) GoBack() error

Navigates backwards in history.

func (*Session) GoForward 

func (s *Session) GoForward() error

Navigates forward in history.

func (*Session) MakeScript 

func (s *Session) MakeScript(js string) Script

/ Returns a script object that can be executed in the browser.

func (*Session) Maximize 

func (s *Session) Maximize() error

Maximizes the current window, as if the user had pressed the maximize button.

No-op if the window is already maximized.

func (*Session) Minimize 

func (s *Session) Minimize() error

Minimizes the current window, as if the user had pressed the minimize button.

No-op if the window is already minimized;

func (*Session) MoveMouse 

func (s *Session) MoveMouse(deltaX float64, deltaY float64, duration time.Duration) error

Simulates moving the pointer from its curent position.

func (*Session) MoveMouseFromElement 

func (s *Session) MoveMouseFromElement(element WebElement, deltaX, deltaY float64, duration time.Duration) error

Simulates moving the pointer from the given element.

func (*Session) MoveMouseTo 

func (s *Session) MoveMouseTo(x float64, y float64, duration time.Duration) error

Simluates moving the pointer to the given CSS pixel coordinates.

func (*Session) Navigate 

func (s *Session) Navigate(url string) error

Navigates to the given url.

func (*Session) OpenPrivateWindow 

func (s *Session) OpenPrivateWindow() (TabHandle, error)

Opens a new tab in a private browser window and returns a handle to it.

func (*Session) OpenTab 

func (s *Session) OpenTab() (TabHandle, error)

Opens a new tab in the current window and returns a handle to it.

func (*Session) OpenWindow 

func (s *Session) OpenWindow() (TabHandle, error)

Opens a tab in a new browser window and returns a handle to it.

func (*Session) PressKey 

func (s *Session) PressKey(key rune) error

Simulates a pressed key.

Any unicode scalar value is allowed.

func (*Session) PressMouse 

func (s *Session) PressMouse(mouseButton MouseButton) error

/ Simulates pressing a mouse button.

func (*Session) ReleaseActions 

func (s *Session) ReleaseActions() error

Releases all keys and pointers that are currently pressed.

func (*Session) ReleaseKey 

func (s *Session) ReleaseKey(key rune) error

Simulates a key being released.

Any unicode scalar value is allowed.

func (*Session) ReleaseMouse 

func (s *Session) ReleaseMouse(mouseButton MouseButton) error

Simulates the release of mouse button.

func (*Session) Reload 

func (s *Session) Reload() error

/ Refreshes the current page.

func (*Session) ScrollAtPointer 

func (s *Session) ScrollAtPointer(deltaX, deltaY float64, duration time.Duration) error

Simulates scrolling the document at the pointer's current position.

func (*Session) ScrollDocument 

func (s *Session) ScrollDocument(deltaX, deltaY float64, duration time.Duration) error

Simulates scrolling the entires viewport.

func (*Session) SendKeysToAlert 

func (s *Session) SendKeysToAlert(text string) error

Sends keys to the input field of a currently displayed alert odal.

func (*Session) SetBoundingBox 

func (s *Session) SetBoundingBox(rect BoundingBox) error

Updates the position and size of the current window.

The supplied width and height values refer to the window outerWidth and outerHeight values, which include scroll bars, title bars, etc.

This is a "best effort" operation. The geometry will be adjusted to as close as possible to the requested bounding box. The new position might even be entirely disregarded.

func (*Session) SetTimeouts 

func (s *Session) SetTimeouts(timeouts Timeouts) error

Sets the timeouts for the current session.

func (*Session) TakeScreenshot 

func (s *Session) TakeScreenshot() ([]byte, error)

Takes a screenshot of the contents of current page.

This includes items not currently in view.

The picture is returned as raw PNG bytes, ready to be written to a file.

type SessionConfig 

type SessionConfig struct {
	// The browser will navigate to this URL on startup
	// If it is empty, the browser loads `about:blank`.
	Url string
	// If `true`, the firefox GUI is displayed.
	Graphical bool
	// If empty, the firefox binary is searched for in the PATH environment variable.
	FirefoxBin string

	// If `true`, the firefox process' STDOUT is inherited from the parent process.
	// Otherwise, it goes to /dev/null
	FirefoxStdout bool

	// If `true`, the firefox process' STDOUT is inherited from the parent process
	// Otherwise, it goes to /dev/null
	FirefoxStderr bool
}

Configuration for starting a firefox session.

It's zero value is ready to use and represents the default configuration.

type ShadowRoot 

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

An opaque sever-assigned identifier that uniquely identifies a shadow root element.

type TabHandle 

type TabHandle string

An opaque server-assigned identifier that uniquely identifies a tab in the current session.

type Timeouts 

type Timeouts struct {
	// Timeout for locating elements on the page
	Find uint64 `json:"implicit"`
	// Timeout for page load
	PageLoad uint64 `json:"pageLoad"`
	// Timeout for script execution
	Script uint64 `json:"script"`
}

Session-wide timeouts

All timeouts are in milliseconds. A timeout of `0` means "no timeout".

type WebElement 

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

An opaque server-assigned identifier that uniquely identifies an element in the current session.

func (WebElement) Clear 

func (w WebElement) Clear() error

Clears the element's input.

func (WebElement) Click 

func (w WebElement) Click() error

Sends a click event to the element.

func (WebElement) FindElement 

func (w WebElement) FindElement(selector string) (WebElement, error)

Returns the first descendant element matching the css selector.

func (WebElement) FindElements 

func (w WebElement) FindElements(selector string) ([]WebElement, error)

Returns a list of all descendant elements matching css selector.

func (WebElement) GetAccessibilityLabel 

func (w WebElement) GetAccessibilityLabel() (string, error)

/ Returns the element's accessibility label.

func (WebElement) GetAccessibilityRole 

func (w WebElement) GetAccessibilityRole() (string, error)

/ Returns the element's accessibility role.

func (WebElement) GetAttribute 

func (w WebElement) GetAttribute(name string) (string, bool, error)

Returns the value of the given attribute on the element.

If the element does not have the given value, the function returns "", false, nil

If an error occurs, the function returns "", false, <error>

func (WebElement) GetBoundingBox 

func (w WebElement) GetBoundingBox() (BoundingBox, error)

Returns the bounding box for the given element.

func (WebElement) GetCssPropertyValue 

func (w WebElement) GetCssPropertyValue(name string) (string, error)

Returns the resolved value of the CSS property with the given name.

func (WebElement) GetShadowRoot 

func (w WebElement) GetShadowRoot() (ShadowRoot, error)

Returns the element's shadow root.

func (WebElement) GetTabName 

func (w WebElement) GetTabName() (string, error)

Returns element's tag name.

func (WebElement) GetText 

func (w WebElement) GetText() (string, error)

Returns the text of the element, if any.

Includes text of all descendant elements.

func (WebElement) IsDisplayed 

func (w WebElement) IsDisplayed() (bool, error)

Returns `true` if the element is currently displayed.

func (WebElement) IsEnabled 

func (w WebElement) IsEnabled() (bool, error)

Returns `true` if the element is currently enabled.

func (WebElement) IsSelected 

func (w WebElement) IsSelected() (bool, error)

Returns `true` if the element is currently selected.

func (WebElement) SendKeyPresses 

func (w WebElement) SendKeyPresses(text string) error

Sends key presses to the element after focusing it.

func (WebElement) TakeScreenshot 

func (w WebElement) TakeScreenshot() ([]byte, error)

Takes a screenshot of the element.

The picture is returned as raw PNG bytes, ready to be written to a file.

Source Files

View all Source files

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.