Describing sign-in and click paths

This article describes in full how to define a sign-in and click paths in a website’s “Testing” tab. It is written for developers. An AI assistant gets it as its guide when it drafts click paths for you (Describing sign-in and click paths). The basics are in Scheduled scans, login areas and click paths.

Prerequisite: a verified domain

Without a verified domain neither a credential nor a click path can be saved; both forms are locked. That is the line between a testing tool and a tool someone could point at other people’s applications. If the verification lapses later, credentials and click paths stop running.

The same applies when saving: everything a step may reach lies on your domain (with all its subdomains). The only exception are the sign-in services you enter explicitly (Describing sign-in and click paths).

The test account

Create an account just for testing, with the lowest rights the area needs to be viewed. Never your own account, never one with administrator rights. The credentials are stored encrypted, decrypted only during a scan, and masked in images and logs.

Better still: test against a staging environment so that nothing can happen in production.

With a form or a flow, a scan signs in once, not again for every page: the other pages take over the session. It is held in the scanner's memory only, is no longer used after 15 minutes without access, or 2 hours at most, and is then deleted the next time the scanner clears up: within seconds when idle, otherwise after the page in progress. This spares your application's sign-in limit. If the session expires along the way, the scan signs in again and checks the same page once more; if your application keeps the sign-in in sessionStorage only, it signs in for each page. The access log of the credentials still shows one entry per page, because the credentials are provided for every page.

Two kinds of credentials

In the “Store credentials” section choose under “Type of credentials”:

• “Simple sign-in form”: username, password and submit are on one page. You give the address of the sign-in page and three selectors. The address must be on your domain.
• “Multi-step sign-in or external sign-in service”: everything that does not fit on one page: choose a method first, then username and password on separate pages, a one-time code, a redirect to a sign-in service. You describe the flow as a sequence of steps (Describing sign-in and click paths).

In both cases a “Success indicator” is mandatory: a selector that is only visible when signed in. Without it the scanner might check the sign-in page instead of your area. After each page the scanner checks that it is still signed in. If the marker is not on the checked page itself, it requests the page you land on after sign-in once more; a marker that appears on every page saves that request.

The step language

A click path and a multi-step sign-in are a JSON list of steps. Each step has an action and the fields it needs. There are exactly eight actions, no free JavaScript:

A click path may have at most 30 steps, a multi-step sign-in at most 15. For a click path the state is checked after every step: the way is the object of the check, not just the destination.

A click path:

[
  {"action": "goto", "url": "/produkt/beispiel"},
  {"action": "click", "selector": "role=button[name=\"Add to cart\"]"},
  {"action": "wait_for", "selector": "[data-test=cart]"},
  {"action": "press", "key": "Tab"},
  {"action": "select", "selector": "#delivery", "value": "Pickup"},
  {"action": "fill", "selector": "#zip", "value": "30159"},
  {"action": "scroll"},
  {"action": "assert_visible", "selector": "[data-test=summary]"}
]

Selectors

Three kinds are allowed:

• CSS, for example #email, [data-test=account], form.login button.
• role=…, for example role=button[name="Sign in"]: the element is found by its role and accessible name, as a screen reader experiences it.
• text=…, for example text=Checkout: the element is found by its visible text.

Prefer role=…: it survives redesigns in which classes and structure change, and an element that can no longer be found this way is usually a problem for people with assistive technology as well.

All other kinds are rejected: xpath=…, id=… and internal:…, selectors starting with // or .. (Playwright reads them as XPath), and chained selectors with >>. The reason: every click is checked on exactly the element it operates (Describing sign-in and click paths), and that only works reliably if the selector reads unambiguously.

Keys

The press action knows only these keys: Tab, Shift+Tab, Escape, Enter, Space, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp and PageDown. Anything else is rejected when saving.

Enter and Space count as a click: the target element is checked, and if it sits in a form, so is the form’s submit button. Enter in a form is a submit without a click.

Placeholders for credentials

Credentials never appear in the text of the steps, only as placeholders, and only in the value field of a fill action:

• {{ zugang.benutzername }} (username)
• {{ zugang.passwort }} (password)
• {{ zugang.einmalcode }} (one-time code): only if you stored the secret for the one-time code. The code itself is generated anew for every scan.

Username and password must each appear at least once, otherwise it is not a sign-in flow. The scanner inserts the values immediately before typing; they never appear in error messages.

Each placeholder only goes into a field made for it. The scanner checks the field itself before typing anything:

• {{ zugang.passwort }} only into a password field (input type="password").
• {{ zugang.einmalcode }} only into a field with autocomplete="one-time-code" or inputmode="numeric", or into a password field.
• {{ zugang.benutzername }} only into a single-line input of type text, email or tel.

Never into a multi-line text area (textarea) or an editable region. If the field does not fit, nothing is typed and the sign-in fails with zugangsdaten_feld_unzulaessig. This way no step can write your password or a one-time code into a comment or search field and submit it, where it could then be read on your site. The username is the exception: it may go into any single-line text field, so it can end up there and become visible in images or in the ARIA tree of a test run.

Multi-step sign-in

In the “Multi-step sign-in or external sign-in service” form you enter a name, username, password, optionally the “Secret for the one-time code (optional)”, the “Sign-in steps” and the “Success indicator”. In addition:

• At most 15 steps.
• The first step is a goto on your domain. The scanner always starts with you. Later, a goto is only allowed on your domain.
• There is no stop_before: a sign-in does not trigger an order.
• After the last step the scanner must be back on your domain and see the success indicator.

A flow for an application with its own two-stage sign-in:

[
  {"action": "goto", "url": "/"},
  {"action": "click", "selector": "role=link[name=\"Sign in\"]"},
  {"action": "fill", "selector": "#username", "value": "{{ zugang.benutzername }}"},
  {"action": "click", "selector": "role=button[name=\"Next\"]"},
  {"action": "fill", "selector": "#password", "value": "{{ zugang.passwort }}"},
  {"action": "click", "selector": "role=button[name=\"Sign in\"]"}
]

A suitable “Success indicator” is [data-test=account].

External sign-in services

If your application redirects to another host for signing in, enter it under “Sign-in services (optional)”, one host per line, for example anmeldung.beispiel-dienst.de. A checkbox goes with it: you confirm that these sign-in services belong to your application and that the account is a test account you set up. Who confirmed and when is recorded.

The rules behind it:

• At most 3 hosts, each exactly as it appears in the browser. No wildcards such as *, no IP addresses, and no host of your own domain (it needs no permission).
• The sign-in service is reached only by a navigation from your flow, such as a click or a redirect, never by a goto.
• It applies only during sign-in. Afterwards, in click paths and when checking pages, only your domain is allowed.
• If you change the list, you confirm again. Without the confirmation the hosts entered do not apply.

A flow through a sign-in service:

[
  {"action": "goto", "url": "/"},
  {"action": "click", "selector": "role=button[name=\"Sign in with service account\"]"},
  {"action": "wait_for", "selector": "#user"},
  {"action": "fill", "selector": "#user", "value": "{{ zugang.benutzername }}"},
  {"action": "fill", "selector": "#secret", "value": "{{ zugang.passwort }}"},
  {"action": "click", "selector": "role=button[name=\"Sign in\"]"}
]

The click on “Sign in with service account” leads to anmeldung.beispiel-dienst.de, the data is entered there, and the flow returns to your application. That host is in the list of sign-in services.

Is the sign-in page checked too?

For users, signing in is part of your offer. If the host of a sign-in service is verified as a website in the same organization, we check its sign-in page as well: once per scan, on arrival and before anything is typed, without state discovery. This check does not sign in: it never enters a password or a one-time code. If such a step comes before the sign-in page in your flow, the check ends there with anmeldeseite_nicht_erreicht. The findings appear in the report under “Sign-in via {host}” and count towards conformance like any other page. Whether the verification holds is decided anew at every scan.

If the host is not verified, the page is not checked. The overview then says that sign-in ran through this host and was not checked, and suggests verifying it as a website. Pages of the sign-in on your own domain, such as the choice of method, belong to the ordinary page selection.

What is never clicked

Nothing is ever ordered, paid, deleted or signed out. These rules cannot be switched off:

• Before every action the element actually operated is checked: its text, aria-label, title, name, value and data-testid. If one of them contains words such as löschen, kündigen, bestellen, kaufen, bezahlen, abmelden, delete, submit order, checkout, it is not clicked. An icon button without text is caught this way too.
• The control the element sits in is checked as well: if your selector hits the icon or part of the label inside a button “Konto löschen” (delete account), the button’s label counts. For a label, the field or button it triggers counts too.
• Exactly the checked element is operated. If it is replaced between the check and the click, or the page changes, the step fails instead of operating another element.
• This applies to click, to Enter and Space (including the form’s submit button) and to the chosen option of select.
• The scanner waits briefly for an element that is still loading. If it does not appear for click, press with a selector or select, it does not count as safe: the step fails after that wait with klick_abgelehnt:nicht_gefunden.
• The only exception: absenden and abschicken (submit) are allowed during sign-in, because submitting the sign-in form is its purpose. Everything else applies there too.
• At runtime the scanner stays on your domain. If a click, a redirect or a key leads to another website, the path ends at once and nothing from that page enters the result.

Stop before

If a click path touches an order or payment, “Stop before” is mandatory: the selector of the button that would trigger the action. The path ends before it, guaranteed.

A path touches one if any of these word parts appears anywhere in its steps (address, selector, value or key), in any letter case: bestell, kaufen, checkout, kasse, zahlung, bezahlen, order, payment, purchase, abschicken, absenden. Without “Stop before” such a click path cannot be saved.

Drafts and approval

What you save in the “Testing” tab runs from the next scan on: saving there is approving. Whatever is created through the API or an AI assistant, by contrast, is always a draft. It sits next to the running steps and runs in no scan until a person approves it. This applies to new click paths, to changes to an existing click path and to the steps of a multi-step sign-in.

Every click path states its status in words:

• “Draft, not running yet”: the path exists only as a draft.
• “Approved, runs in scans”: the approved steps run in every scan.
• “Approved, a new draft awaits approval”: the previous steps keep running; a draft sits next to them.

Below a draft you see what it changes, step by step as text: “unchanged”, “changed” (with before and now), “new” and “removed”. The comparison goes by position, so an inserted step shows up as a series of changed steps. It also says when and how the draft was created, for example “via the API, token “Editor Lena”, responsible: …”, and how the last test run of exactly this draft went. If there was none, it says “Not tried yet”. You can still approve the draft; the note only tells you what you are approving.

“Approve” turns the draft’s steps into the running steps; “Discard” deletes only the draft. Every member who may edit click paths may approve. On approval:

• The draft is checked again against today’s rules. If the domain is no longer verified or a step has become invalid, the approval is refused with a message, and the running steps stay as they are.
• What is approved is exactly the draft you saw. If an assistant replaced it while the page was open, the approval is refused; the page then shows the new draft.
• Approving the steps of a multi-step sign-in lifts a pause (Describing sign-in and click paths): a new flow is a new attempt. The exception is a credential whose sign-in page lies outside your domain.

Working with an AI assistant

An AI assistant in your editor can draft and try click paths for you. It talks to the service’s MCP server for this; if you do not use an assistant, the API does the same (Editing click paths through the API). The assistant sees only the website its token is bound to, and everything it saves is a draft (Describing sign-in and click paths).

Create a token and grant the right

1. Open the website’s “Embedding” tab. Only the “Owner” and “Administration” roles see it.
2. Give it a name you will recognise later, such as “Editor Lena”, and choose “Create token”. The token is shown only once.
3. On the new token, choose “Allow editing click paths”. Only then may it read, draft and try click paths.

Whoever grants the right is recorded as the responsible person on every draft created through this token. If she loses her role, the right lapses: the assistant can still read, but can no longer draft or try anything until someone grants the right again.

Set up the assistant

The MCP server’s address is https://barrierepruefung.de/mcp. The token is sent as the header Authorization: Bearer …. Never put the token into a file that is committed with your code.

GitHub Copilot in VS Code: create the file .vscode/mcp.json in the project. The inputs prompt asks for the token on first start, VS Code stores it securely for later starts, and the file itself does not contain it:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "a11y-token",
      "description": "Token for click paths",
      "password": true
    }
  ],
  "servers": {
    "a11y": {
      "type": "http",
      "url": "https://barrierepruefung.de/mcp",
      "headers": {
        "Authorization": "Bearer ${input:a11y-token}"
      }
    }
  }
}

GitHub Copilot in JetBrains: in Copilot Chat in agent mode, open the MCP settings via the tools icon; the file mcp.json opens. There the header goes under requestInit.headers:

{
  "servers": {
    "a11y": {
      "url": "https://barrierepruefung.de/mcp",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer YOUR_TOKEN"
        }
      }
    }
  }
}

GitHub Copilot in Visual Studio: add the server to the file %USERPROFILE%\.mcp.json for your user account, not to the solution’s .mcp.json, which is often checked in. The structure is the same, servers with url. Microsoft does not describe how Visual Studio expects a custom header such as Authorization; its documentation only names OAuth sign-in for remote servers. Please check the vendor’s documentation whether headers or requestInit.headers applies.

Claude Code: one command in the terminal. Without a scope option the entry applies only to you in this project and does not end up in the repository:

claude mcp add --transport http a11y https://barrierepruefung.de/mcp --header "Authorization: Bearer YOUR_TOKEN"

Cursor: add the server to the global file ~/.cursor/mcp.json, not to the project’s .cursor/mcp.json:

{
  "mcpServers": {
    "a11y": {
      "url": "https://barrierepruefung.de/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Not verified is GitHub Copilot’s cloud coding agent, which works inside GitHub itself: we do not know whether it can send such a header to a remote MCP server. The variants in VS Code, Visual Studio and JetBrains are not affected by this.

What the assistant may do

The server offers these tools:

There is also the prompt klickpfad_anleitung (this article) and the schemas schema://klickpfad and schema://anmeldeablauf.

A test run walks the path once in the browser but checks nothing for accessibility. It follows the same rules as a scan: only your domain, never order, pay, delete or sign out (Describing sign-in and click paths). It ends at the first step that fails. From a page outside your domain there is neither image nor snapshot, only its origin. In the images, password, email and phone fields are masked, as are fields whose name or autocomplete hints at a password, token, secret or card number. What other fields contain is visible.

The assistant may not:

• approve a draft. A person always does that in the “Testing” tab.
• see or set credentials: neither user name, password nor the one-time code secret, and no sign-in services or their confirmation. Its steps contain placeholders only. The scanner types a password and a one-time code only into fields made for them (Describing sign-in and click paths), so they cannot end up in a comment field; the username goes into any single-line text field, so it can show up in images or in the ARIA tree of a test run.
• create or delete a credential, delete a click path or start a scan.
• reach any website other than its token’s.

Limits of test runs

• Per website at most 20 test runs per hour, of which at most 5 with sign-in.
• Only one test run per website at a time. A second one is refused, not queued.
• If sign-in fails in a test run, test runs with sign-in are blocked for 30 minutes. This protects your test account from being locked by the sign-in service. A test run does not count towards the credential’s pause.
• A test run’s result and images are deleted after 24 hours. After that the draft says “Not tried yet” again.
• probelauf_ergebnis waits up to 25 seconds for the test run to finish.
• Test runs are only available in a plan with click paths and only with a verified domain.

When a click path fails

Every click path has a card in the “Testing” tab showing its state from the last completed scan: succeeded, failed or “not checked”. Failed means a step could not be performed and the scanner measured why. The card names the step, the width and the reason in one sentence, plus what you can do; the selector and the measured values are under “Technische Angabe”. It also shows whether the path was changed since the scan (“checked again in the next scan”). “Go to the scan” opens the scan, “Start test run” tries the path at once.

Measuring happens only at a step that failed, in the page the scanner has already loaded: briefly, without reloading the page and without another request to your website. Only numbers and truth values (hits, visible, operable, detached, page changed) and at most a path without a query go into the finding, never a typed value and never a browser message.

A test run goes through every width of the scan profile in turn and ends at the first failure. It counts as one test run, not one per width. Sign-in happens once per device class; desktop and the narrow width share one. The result names every step per width with an image and, if it failed, the finding. So you see whether a path fails only at the width where a menu sits behind a button.

Not checked is not failed. “not checked” appears when the scanner could not bring the path to a step, for instance because of a failed sign-in (the brake, Describing sign-in and click paths), throttling by your website, an expired deadline, a spent budget or a proxy error. Nothing is wrong with the path then; the card names the reason, and once the cause is removed the path is checked in the next scan. For a reason we cannot name it says “aus einem technischen Grund” (for a technical reason). The reasons themselves are listed under Describing sign-in and click paths.

How to fix a path. The interface does not edit existing click paths step by step. “Create corrected click path” leads to the “Create a journey” form: create the corrected path there anew and delete the old one (“Delete journey”). Or have an AI assistant or the API write a draft for the existing path (Describing sign-in and click paths, Editing click paths through the API) and approve it in the “Testing” tab. Try it with a test run before approving; the draft shows how that test run went.

Failure reasons

If something fails, the scan names a reason. It appears on the page or in the run:

Pause after failures

A failed sign-in costs one attempt per scan, not one per page: after the first failure the remaining pages of the same run are not attempted (reason anmeldung_fehlgeschlagen), nor is the check of the sign-in page (anmeldeseite_gebremst). For these pages the credentials are not even decrypted. This protects the test account, because some applications lock it after a few failed attempts, and to a third party that would look like an attack on credentials. If sign-in only fails in the middle of a scan, the scan is “partially completed”; the overview and the e-mail then name the reason, and the remaining pages count as not checked.

If sign-in fails 3 runs in a row, the credentials are paused. The reason is shown on them; after the correction (“Reactivate credentials”) it continues. Credentials switched off because of a sign-in address outside your domain do not have this button: they can only be used again after deleting them and creating them anew with an address on your domain.

How many credentials and click paths your plan allows is in Scheduled scans, login areas and click paths.