Models module

Data models for Lynqa API: test steps, test data, and test run context.

This package groups the models by concern:

pylynqa.models.common — shared value objects (guidance, secrets, attachments).
pylynqa.models.tests — test-run request/creation payloads.
pylynqa.models.commands — browser command read models and the command parser.
pylynqa.models.reports — step execution reports.
pylynqa.models.errors — client exceptions.

Every public name is re-exported here, so from pylynqa.models import X keeps working.

class pylynqa.models.AssertionChecking(assertion: str, checked: bool)

Bases: object

A single assertion evaluated during a step.

Parameters:

assertion – Human-readable assertion text.
checked – Whether the assertion evaluated to true.

assertion: str

checked: bool

classmethod from_dict(d: dict) → AssertionChecking: Build from a JSON-decoded dict.

class pylynqa.models.AssertionsReport(assertions: list[AssertionChecking] = <factory>, screenshot: str | None = None)

Bases: object

The assertions evaluated for a step, present for success or failed steps.

Parameters:

assertions – Individual assertion checks.
screenshot – UUID of the screenshot taken at assertion time.

assertions: list[AssertionChecking]

classmethod from_dict(d: dict) → AssertionsReport: Build from a JSON-decoded dict.

screenshot: str | None = None

class pylynqa.models.Attachment(name: str, id: str)

Bases: object

A file attachment returned by the API (server-assigned id).

Parameters:

name – File name, e.g. 'invoice_260313.pdf'.
id – UUID of the attachment assigned by the server.

id: str

name: str

Bases: object

A click browser command executed during a step.

Parameters:

name – Command discriminator ('click').
button – Mouse button used, e.g. 'left'.
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or ClickCommandSuccess).

button: str | None = None

classmethod from_dict(d: dict) → ClickCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

response: ErrorResponse | ClickCommandSuccess | None = None

screenshot: str | None = None

class pylynqa.models.ClickCommandResponse(new_url: str | None = None)

Bases: object

Result payload of a successful click command.

Parameters:: new_url – URL after the click, if navigation occurred.

classmethod from_dict(d: dict) → ClickCommandResponse: Build from a JSON-decoded response dict.

new_url: str | None = None

class pylynqa.models.ClickCommandSuccess(success: list[ClickCommandResponse] = <factory>)

Bases: object

Success outcome of a click command.

Parameters:: success – One entry per resolved click.

classmethod from_dict(d: dict) → ClickCommandSuccess: Build from a JSON-decoded response dict.

success: list[ClickCommandResponse]

class pylynqa.models.CreateAttachment(name: str, data: str)

Bases: object

A file attachment to include with a test run (creation only).

Parameters:

name – File name, e.g. 'invoice_260313.pdf'.
data – Base64-encoded data URI, e.g. 'data:text/plain;base64,SGVsbG8gd29ybGQh'.

data: str

name: str

to_dict() → dict: Transform to a JSON-compatible dict.

class pylynqa.models.CreateGherkinTest(url: str, scenario: str, name: str | None = None, context: TestRunContext | None = None, guidance: list[TextualData] = <factory>, attachments: list[CreateAttachment] = <factory>, webhooks: list[str] = <factory>)

Bases: object

A Gherkin (BDD) test to execute (creation payload).

Mirrors the CreateGherkinTest schema. Used both by add_gherkin_test_run() and, together with CreateTest, inside a add_test_batch() call.

Parameters:

url – URL of the system under test.
scenario – Full Gherkin scenario text, including Given, When, and Then steps.
name – Optional human-readable name for this run.
context – Optional locale and secrets context.
guidance – Optional global guidance hints for the agent.
attachments – Optional files attached to the test run (base64-encoded).
webhooks – Optional list of webhook URLs to notify once the test run has ended.

attachments: list[CreateAttachment]

context: TestRunContext | None = None

guidance: list[TextualData]

name: str | None = None

scenario: str

to_dict() → dict

Serialise to a JSON-compatible dict, omitting unset optional fields.

Returns:: Dict with url and scenario always present.

url: str

webhooks: list[str]

class pylynqa.models.CreateTest(url: str, steps: list[CreateTestStep] = <factory>, name: str | None = None, context: TestRunContext | None = None, guidance: list[TextualData] = <factory>, attachments: list[CreateAttachment] = <factory>, webhooks: list[str] = <factory>)

Bases: object

A manual test to execute (creation payload).

Mirrors the CreateTest schema. Used both by add_test_run() and, together with CreateGherkinTest, inside a add_test_batch() call.

Parameters:

url – URL of the system under test, e.g. 'https://example.com'.
steps – Ordered list of test steps to execute.
name – Optional human-readable name for this run.
context – Optional locale and secrets context.
guidance – Optional global guidance hints for the agent.
attachments – Optional files attached to the test run (base64-encoded).
webhooks – Optional list of webhook URLs to notify once the test run has ended.

attachments: list[CreateAttachment]

context: TestRunContext | None = None

guidance: list[TextualData]

name: str | None = None

steps: list[CreateTestStep]

to_dict() → dict

Serialise to a JSON-compatible dict, omitting unset optional fields.

Returns:: Dict with url and steps always present.

url: str

webhooks: list[str]

class pylynqa.models.CreateTestStep(action: str, expected_result: str | None = None, guidance: list[TextualData] = <factory>, attachments: list[CreateAttachment] = <factory>)

Bases: object

A single step to include when creating a test run.

Parameters:

action – Human-readable description of the action to perform, e.g. 'Click on the "Login" button'.
expected_result – Optional assertion that should hold after the action is executed, e.g. 'The user is redirected to /dashboard'.
guidance – Optional guidance hints to help the agent execute this step.
attachments – Optional file attachments for this step (base64-encoded).

action: str

attachments: list[CreateAttachment]

expected_result: str | None = None

guidance: list[TextualData]

to_dict() → dict

Serialise to a JSON-compatible dict.

Returns:: Dict with action and, when set, optional fields.

Bases: object

A doubleClick browser command executed during a step.

Parameters:

name – Command discriminator ('doubleClick').
button – Mouse button used, e.g. 'left'.
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or DoubleClickCommandSuccess).

button: str | None = None

classmethod from_dict(d: dict) → DoubleClickCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

response: ErrorResponse | DoubleClickCommandSuccess | None = None

screenshot: str | None = None

class pylynqa.models.DoubleClickCommandResponse(new_url: str | None = None)

Bases: object

Result payload of a successful doubleClick command.

Parameters:: new_url – URL after the double click, if navigation occurred.

classmethod from_dict(d: dict) → DoubleClickCommandResponse: Build from a JSON-decoded response dict.

new_url: str | None = None

class pylynqa.models.DoubleClickCommandSuccess(success: list[DoubleClickCommandResponse] = <factory>)

Bases: object

Success outcome of a doubleClick command.

Parameters:: success – One entry per resolved double click.

classmethod from_dict(d: dict) → DoubleClickCommandSuccess: Build from a JSON-decoded response dict.

success: list[DoubleClickCommandResponse]

class pylynqa.models.DragCommand(name: str, html_element: str | None = None, screenshot: str | None = None, response: ErrorResponse | DragCommandSuccess | None = None)

Bases: object

A drag browser command executed during a step.

Parameters:

name – Command discriminator ('drag').
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or DragCommandSuccess).

classmethod from_dict(d: dict) → DragCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

response: ErrorResponse | DragCommandSuccess | None = None

screenshot: str | None = None

class pylynqa.models.DragCommandSuccess(success: bool = False)

Bases: object

Success outcome of a drag command.

Parameters:: success – Whether the drag succeeded.

classmethod from_dict(d: dict) → DragCommandSuccess: Build from a JSON-decoded response dict.

success: bool = False

class pylynqa.models.ErrorResponse(error: str)

Bases: object

Failure outcome of a browser command.

Parameters:: error – Machine-readable error cause, e.g. 'not_visible_element' or 'host_not_reachable'.

error: str

classmethod from_dict(d: dict) → ErrorResponse: Build from a JSON-decoded response dict.

Bases: object

A fill browser command executed during a step.

Parameters:

name – Command discriminator ('fill').
value – Value used to fill the input.
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or FillCommandSuccess).

classmethod from_dict(d: dict) → FillCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

response: ErrorResponse | FillCommandSuccess | None = None

screenshot: str | None = None

value: str | None = None

class pylynqa.models.FillCommandResponse(new_value: str | None = None)

Bases: object

Result payload of a successful fill command.

Parameters:: new_value – Value present in the field after filling.

classmethod from_dict(d: dict) → FillCommandResponse: Build from a JSON-decoded response dict.

new_value: str | None = None

class pylynqa.models.FillCommandSuccess(success: list[FillCommandResponse] = <factory>)

Bases: object

Success outcome of a fill command.

Parameters:: success – One entry per resolved fill.

classmethod from_dict(d: dict) → FillCommandSuccess: Build from a JSON-decoded response dict.

success: list[FillCommandResponse]

class pylynqa.models.GenericCommand(name: str, html_element: str | None = None, screenshot: str | None = None, raw: dict = <factory>)

Bases: object

Fallback command used when the name discriminator is not recognised.

Preserves forward compatibility with command types introduced after this client was released.

Parameters:

name – Raw command name.
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
raw – The unparsed command dict as received from the API.

classmethod from_dict(d: dict) → GenericCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

raw: dict

screenshot: str | None = None

Bases: object

A goto browser command executed during a step.

Parameters:

name – Command discriminator ('goto').
url – URL to reach.
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or GotoCommandSuccess).

classmethod from_dict(d: dict) → GotoCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

response: ErrorResponse | GotoCommandSuccess | None = None

screenshot: str | None = None

url: str | None = None

class pylynqa.models.GotoCommandResponse(url: str | None = None)

Bases: object

Result payload of a successful goto command.

Parameters:: url – URL that was reached.

classmethod from_dict(d: dict) → GotoCommandResponse: Build from a JSON-decoded response dict.

url: str | None = None

class pylynqa.models.GotoCommandSuccess(success: list[GotoCommandResponse] = <factory>)

Bases: object

Success outcome of a goto command.

Parameters:: success – One entry per resolved navigation.

classmethod from_dict(d: dict) → GotoCommandSuccess: Build from a JSON-decoded response dict.

success: list[GotoCommandResponse]

class pylynqa.models.HoverCommand(name: str, html_element: str | None = None, screenshot: str | None = None, response: ErrorResponse | HoverCommandSuccess | None = None)

Bases: object

A hover browser command executed during a step.

Parameters:

name – Command discriminator ('hover').
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or HoverCommandSuccess).

classmethod from_dict(d: dict) → HoverCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

response: ErrorResponse | HoverCommandSuccess | None = None

screenshot: str | None = None

class pylynqa.models.HoverCommandSuccess(success: bool = False)

Bases: object

Success outcome of a hover command.

Parameters:: success – Whether the hover succeeded.

classmethod from_dict(d: dict) → HoverCommandSuccess: Build from a JSON-decoded response dict.

success: bool = False

exception pylynqa.models.LynqaClientError(status_code: int, error: str = '', message: str = '')

Bases: Exception

Raised when the Lynqa API returns a non-2xx HTTP response.

Parameters:

status_code – HTTP status code returned by the server.
error – Short error label from the response body (e.g. 'Unauthorized').
message – Human-readable description from the response body (e.g. 'Missing authentication method').

Common status codes:

400 - Request body is malformed.
401 - Authentication failed (invalid or missing API key).
403 - Not enough credits to execute the test.
404 - Resource not found.
410 - Test run has expired.
422 - URL is not safe to test.
429 - Too many requests (rate limit exceeded).

Bases: object

A pressKey browser command executed during a step.

Parameters:

name – Command discriminator ('pressKey').
value – Sequence of keys, comma separated.
keys_sequence – Sequence of keys as a list.
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or PressKeyCommandSuccess).

classmethod from_dict(d: dict) → PressKeyCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

keys_sequence: list[str]

name: str

response: ErrorResponse | PressKeyCommandSuccess | None = None

screenshot: str | None = None

value: str | None = None

class pylynqa.models.PressKeyCommandResponse(new_url: str | None = None)

Bases: object

Result payload of a successful pressKey command.

Parameters:: new_url – URL after pressing the keys, if navigation occurred.

classmethod from_dict(d: dict) → PressKeyCommandResponse: Build from a JSON-decoded response dict.

new_url: str | None = None

class pylynqa.models.PressKeyCommandSuccess(success: list[PressKeyCommandResponse] = <factory>)

Bases: object

Success outcome of a pressKey command.

Parameters:: success – One entry per resolved key press.

classmethod from_dict(d: dict) → PressKeyCommandSuccess: Build from a JSON-decoded response dict.

success: list[PressKeyCommandResponse]

class pylynqa.models.ScrollCommand(name: str, html_element: str | None = None, screenshot: str | None = None, response: ErrorResponse | ScrollCommandSuccess | None = None)

Bases: object

A scroll browser command executed during a step.

Parameters:

name – Command discriminator ('scroll').
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or ScrollCommandSuccess).

classmethod from_dict(d: dict) → ScrollCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

response: ErrorResponse | ScrollCommandSuccess | None = None

screenshot: str | None = None

class pylynqa.models.ScrollCommandResponse(direction: str | None = None, delta: float | None = None)

Bases: object

Result payload of a successful scroll command.

Parameters:

direction – Direction of the scroll, 'up' or 'down'.
delta – Number of pixels scrolled.

delta: float | None = None

direction: str | None = None

classmethod from_dict(d: dict) → ScrollCommandResponse: Build from a JSON-decoded response dict.

class pylynqa.models.ScrollCommandSuccess(success: list[ScrollCommandResponse] = <factory>)

Bases: object

Success outcome of a scroll command.

Parameters:: success – One entry per resolved scroll.

classmethod from_dict(d: dict) → ScrollCommandSuccess: Build from a JSON-decoded response dict.

success: list[ScrollCommandResponse]

Bases: object

A select browser command executed during a step.

Parameters:

name – Command discriminator ('select').
value – Concatenated selected options.
options – Selected options.
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or SelectCommandSuccess).

classmethod from_dict(d: dict) → SelectCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

options: list[str]

response: ErrorResponse | SelectCommandSuccess | None = None

screenshot: str | None = None

value: str | None = None

class pylynqa.models.SelectCommandResponse(selected_options: list[str] = <factory>)

Bases: object

Result payload of a successful select command.

Parameters:: selected_options – Options selected as a result of the command.

classmethod from_dict(d: dict) → SelectCommandResponse: Build from a JSON-decoded response dict.

selected_options: list[str]

class pylynqa.models.SelectCommandSuccess(success: list[SelectCommandResponse] = <factory>)

Bases: object

Success outcome of a select command.

Parameters:: success – One entry per resolved select.

classmethod from_dict(d: dict) → SelectCommandSuccess: Build from a JSON-decoded response dict.

success: list[SelectCommandResponse]

class pylynqa.models.StepReport(commands: list[Command] = <factory>, status: str = '', start: str | None = None, end: str | None = None, assertions_report: AssertionsReport | None = None, test_verdict_cause: str | None = None, error: str | None = None)

Bases: object

The execution report of a single test step.

Depending on the step status only some fields are populated (e.g. assertions_report is present for success or failed steps, error only for error steps).

Parameters:

commands – Browser commands executed during this step.
status – Step execution status, e.g. 'success', 'failed', 'error'.
start – Step start date (ISO 8601), present once the step has started.
end – Step end date (ISO 8601), present once the step has finished.
assertions_report – Assertions evaluated, present for success or failed steps.
test_verdict_cause – Human-readable failure reason, present when status is failed.
error – Internal error cause, present when status is error.

assertions_report: AssertionsReport | None = None

commands: list[Command]

end: str | None = None

error: str | None = None

classmethod from_dict(d: dict) → StepReport

Build from a JSON-decoded step report dict.

Parameters:: d – Step report dict as returned by the API.
Returns:: A typed StepReport.

start: str | None = None

status: str = ''

test_verdict_cause: str | None = None

class pylynqa.models.TestData(name: str, value: str)

Bases: object

A name/value pair used to inject secrets or test data into test steps.

Parameters:

name – Name of the data entry, e.g. 'password'.
value – Value of the data entry, e.g. 'mys3cr3t!'.

name: str

to_dict() → dict

Serialise to a JSON-compatible dict.

Returns:: Dict with name and value.

value: str

class pylynqa.models.TestRunContext(browser_locale: str | None = None, client_datetime: str | None = None, secrets: list[TestData] = <factory>)

Bases: object

Optional context attached to a test run.

Provides locale information and secrets that the Lynqa engine can use when executing the test steps.

Parameters:

browser_locale – Browser locale code, formatted (ISO 639-1)_(ISO 3166-1 alpha-2)(.UTF-8), e.g. 'fr_FR', 'en_US.UTF-8', or 'es_ES'. Defaults to en_US server-side when omitted.
client_datetime – Human-readable local date/time string passed to the agent, e.g. 'Thu Feb 26 2026 09:26:12 GMT+0100'.
secrets – List of TestData entries that will be injected into the test steps at execution time.

browser_locale: str | None = None

client_datetime: str | None = None

secrets: list[TestData]

to_dict() → dict

Serialise to a JSON-compatible dict, omitting unset fields.

Returns:: Dict representation of the context.

Bases: object

Filter criteria for query_test_runs().

All fields are optional; omitted fields are not sent in the request body.

Parameters:

statuses – Keep only runs with these statuses. Allowed values: 'waiting', 'running', 'success', 'failed', 'error', 'stopped', 'not_run'.
relative_period – Relative time window, e.g. TimePeriod(count=3, unit='h') for the last 3 hours.
start_date – Start of an explicit date range (ISO 8601).
end_date – End of an explicit date range (ISO 8601).
api_key_ids – Keep only runs created by these API key IDs.
test_run_ids – Keep only runs with these IDs.

api_key_ids: list[str] | None = None

end_date: str | None = None

relative_period: TimePeriod | None = None

start_date: str | None = None

statuses: list[str] | None = None

test_run_ids: list[str] | None = None

to_dict() → dict: Transform to a JSON-compatible dict.

class pylynqa.models.TestStep(action: str, expected_result: str | None = None, guidance: list[TextualData] = <factory>, attachments: list[Attachment] = <factory>)

Bases: object

A single step returned by the API for a test run.

Parameters:

action – Human-readable description of the action performed.
expected_result – Assertion associated with this step, if any.
guidance – Guidance hints attached to this step.
attachments – File attachments returned by the server (read-only, server-assigned ids).

action: str

attachments: list[Attachment]

expected_result: str | None = None

guidance: list[TextualData]

class pylynqa.models.TextualData(text: str)

Bases: object

A guidance hint passed to the Lynqa agent during test execution.

Parameters:: text – Plain-text guidance, e.g. 'The user is between 18 and 49'.

text: str

to_dict() → dict: Transform to a JSON-compatible dict.

class pylynqa.models.TimePeriod(count: int, unit: str)

Bases: object

A relative time window used in TestRunsFilter.

Parameters:

count – Number of units, e.g. 3 for “last 3 hours”.
unit – Time unit — 'm' minutes, 'h' hours, 'd' days, 'M' months.

count: int

to_dict() → dict: Transform to a JSON-compatible dict.

unit: str

Bases: object

A type browser command executed during a step.

Parameters:

name – Command discriminator ('type').
value – Value typed.
html_element – Plain-text description of the targeted element, if any.
screenshot – Screenshot UUID captured after the command, if any.
response – Command outcome (ErrorResponse or TypeCommandSuccess).

classmethod from_dict(d: dict) → TypeCommand: Build from a JSON-decoded command dict.

html_element: str | None = None

name: str

response: ErrorResponse | TypeCommandSuccess | None = None

screenshot: str | None = None

value: str | None = None

class pylynqa.models.TypeCommandSuccess(success: bool = False)

Bases: object

Success outcome of a type command.

Parameters:: success – Whether the type succeeded.

classmethod from_dict(d: dict) → TypeCommandSuccess: Build from a JSON-decoded response dict.

success: bool = False

pylynqa.models.parse_command(d: dict) → Command

Parse a single command dict into the matching typed command object.

Dispatches on the name discriminator. Unknown names fall back to GenericCommand.

Parameters:: d – JSON-decoded command dict.
Returns:: A typed command object.