Authenticated Testing

To test areas of an application that require a login, describe the authentication flow in your configuration file. Shannon runs the flow at scan start and reuses the authenticated session for the rest of the run.

This page focuses on writing the authentication block. For the surrounding configuration file, see the Configuration guide.

The authentication block

authentication:
  login_type: form
  login_url: "https://your-app.com/login"
  credentials:
    username: "test@example.com"
    password: "yourpassword"
    totp_secret: "LB2E2RX7XFHSTGCK"

  login_flow:
    - "Type $username into the email field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"

  success_condition:
    type: url_contains
    value: "/dashboard"

Writing the login flow

Log in once in a fresh private browser window, then write the steps in the same order you perform them:

• When typing into a field, reference the field by its exact label or placeholder.
• When clicking a button, reference the exact button text.

login_flow:
  - "Type $username in <exact email field label or placeholder>"
  - "Click <exact button text>"
  - "Type $password in <exact password field label or placeholder>"
  - "Click <exact button text>"
  - "If prompted for 2FA, type $totp in <exact code field label or placeholder>"
  - "Click <exact button text>"

Supported placeholders

At runtime, Shannon replaces these placeholders with the credentials passed in the config:

Placeholder	Resolves to
$username	credentials.username
$password	credentials.password
$totp	current TOTP code from credentials.totp_secret
$email_address	credentials.email_login.address
$email_password	credentials.email_login.password
$email_totp	current TOTP code from credentials.email_login.totp_secret

Two-factor authentication

Provide totp_secret under credentials and reference $totp in your login flow. Shannon generates the current time-based code at runtime.

Email-based login (magic links and email OTP)

For magic-link or email-OTP flows, supply mailbox credentials so Shannon can read the login email:

credentials:
  username: "test@example.com"
  password: "yourpassword"
  email_login:
    address: "inbox@example.com"
    password: "mailbox-password"
    totp_secret: "JBSWY3DPEHPK3PXP"

Reference $email_address, $email_password, and $email_totp in the login flow as needed.

Success condition

The success_condition tells Shannon how to confirm that login worked. A common pattern is checking that the browser lands on a known post-login URL:

success_condition:
  type: url_contains
  value: "/dashboard"