SPHYNX
esc
  • Loading
Open console

Guides

Fill a form

Find the fields on a page, fill them and submit, in one request.

This guide logs in to a site over HTTP: one call to see what is on the page, one call to fill the form and submit it. No browser library is needed.

Before you start

You need an API key and a running session. The snippets read the base URL and the key from the environment and keep the session ID in SESSION.

Shell
export SPHYNX_URL=http://localhost:8080   # your deployment's base URL
export SPHYNX_API_KEY=sx_live_...

SESSION=$(curl -s -X POST "$SPHYNX_URL/v1/sessions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_url": "https://example.com/login"}' | jq -r .id)

start_url is loaded before the call returns, so the session starts on the login page. If it does not load, the call fails with navigation_failed or navigation_timeout and no session is returned.

https://example.com/login stands in for the login page of your site: a form with an email field, a password field and a Sign in button.

Find the fields

POST/v1/sessions/{id}/elements with an empty body lists what a person could interact with: links, buttons, inputs, selects, textareas and elements with a click handler or button role.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/elements" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Every element comes back with a unique selector and an absolute xpath. Either can be passed straight back as a locator.

200
{
  "count": 3,
  "truncated": false,
  "elements": [
    {
      "selector": "#email",
      "xpath": "/html/body/form[1]/input[1]",
      "tag": "input",
      "name": "email",
      "type": "email",
      "placeholder": "Email",
      "visible": true
    },
    {
      "selector": "#login > input:nth-of-type(2)",
      "xpath": "/html/body/form[1]/input[2]",
      "tag": "input",
      "name": "password",
      "type": "password",
      "placeholder": "Password",
      "visible": true
    },
    {
      "selector": "#login > button",
      "xpath": "/html/body/form[1]/button[1]",
      "tag": "button",
      "text": "Sign in",
      "type": "submit",
      "visible": true
    }
  ]
}

Fill and submit

POST/v1/sessions/{id}/actions runs a list of steps in order. Fill both fields, click the button and wait for the page that follows.

curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/actions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {"type": "fill",  "selector": "#email", "value": "me@example.com"},
      {"type": "fill",  "xpath": "//input[@name=\"password\"]", "value": "hunter2"},
      {"type": "click", "text": "Sign in"},
      {"type": "wait",  "selector": ".dashboard", "timeout_ms": 10000}
    ]
  }'

The three locators are interchangeable. Use whichever is shortest for the element: a CSS selector, an xpath, or the visible text.

Check the result

The response lists every step that ran, then the page the session ended on. ok is true only when every step succeeded.

200
{
  "ok": true,
  "completed": 4,
  "results": [
    { "type": "fill", "ok": true, "duration_ms": 96 },
    { "type": "fill", "ok": true, "duration_ms": 88 },
    { "type": "click", "ok": true, "duration_ms": 2140 },
    { "type": "wait", "ok": true, "duration_ms": 640 }
  ],
  "url": "https://example.com/dashboard",
  "title": "Dashboard"
}

The click took about 2 s: the pointer moves to the element along a human-like path, which takes about 1.5 to 4 s. A fill on a field in view takes milliseconds. Set your client's timeout for the whole list. Timings for every step are under Actions.

When a step fails

Steps stop at the first failure. The call still returns 200, with ok: false, and the failed step carries the error. Later steps do not run.

200 · the click found nothing
{
  "ok": false,
  "completed": 2,
  "results": [
    { "type": "fill", "ok": true, "duration_ms": 96 },
    { "type": "fill", "ok": true, "duration_ms": 88 },
    { "type": "click", "ok": false, "duration_ms": 31,
      "error": { "code": "element_not_found", "message": "no element matched" } }
  ],
  "url": "https://example.com/login",
  "title": "Log in"
}

What can go wrong

These codes appear on the failed step, inside a 200 response:

CodeWhen
element_not_foundNo element matched the locator
wait_timeoutA wait step timed out
no_page_loadedThe tab is blank. Start with a navigate step or a start_url
invalid_requestA selector or XPath the page cannot parse. The steps before it have run

These fail the whole call:

HTTPCodeWhen
400invalid_requestAn unknown type, a missing field or two locators on one step. Nothing runs. details.index names the step
409session_in_useAnother drive call has been running on this session for more than 3 s. Retry
410session_closedThe session has ended

Fill or type

fill sets the whole value at once. type types key by key with human timing, about 0.1 s per character. press sends one key, such as Enter to submit.

Type and press Enter
{
  "actions": [
    { "type": "type", "selector": "#search", "value": "27-inch monitor" },
    { "type": "press", "key": "Enter" }
  ]
}

Close the session

A session keeps running until it is deleted, times out or sits idle for idle_timeout_seconds. Delete it when you are done.

curl
curl -s -X DELETE "$SPHYNX_URL/v1/sessions/$SESSION" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"

Next

  • Actions: every step type and its fields.
  • Elements: find elements by selector, XPath or text.
  • Extract data: read values out of the page you landed on.