Testing Authentication and Login Flows

Test authenticated features efficiently. Configure login credentials, set up authentication URLs, and reuse sessions across test cases.

Setting Login Credentials​

Testpilot uses environment variables to securely manage your login credentials:

# Set your username and password as environment variables
export TESTPILOT_USERNAME="your-username"
export TESTPILOT_PASSWORD="your-password"

These credentials will be used whenever a test requires authentication. You can set these in your shell profile, CI environment, or just before running your tests. You can also use the secret manager of your choice to set these credentials before running Testpilot

Configuring Custom Environment Variables For Login

Alternatively, you can also use custom env-vars of your own choosing by specifying them in the pilot file:

name: "Configuring Environment Variables for Login"
login:
  username: ${MY_CUSTOM_USERNAME}
  password: ${MY_CUSTOM_PASSWORD}
cases:
  - ... # omitted for clarity

Configuring Login URL ​

To tell Testpilot where to log in, add a login.url field to your pilot file:

name: "Authenticated Tests Example"
login:
  url: "https://example.com/login"
cases:
  - id: "dashboard-test"
    name: "View Dashboard"
    description: "Test authenticated dashboard access"
    url: "https://example.com/dashboard"
    steps:
      - "Verify the dashboard has loaded"
      - "Check that user information is displayed correctly"
      - "Navigate to settings page"

The login.url parameter tells Testpilot where to perform the authentication before running your tests.

How Authentication Works For Websites​

When you provide both a login URL and credentials, Testpilot will:

1. Launch a browser session
2. Navigate to the login URL
3. Automatically detect and fill in username and password fields
4. Submit the login form
5. Verify successful authentication
6. Reuse this authenticated session for all your test cases

This means you only authenticate once, and all your test cases benefit from the same authenticated session, saving time and reducing flakiness.

Example: Testing Authenticated Features in a Website​

Here’s a complete example of testing features that require authentication:

name: "User Account Tests"
login:
  url: "https://myapp.com/login"
  username: ${MY_CUSTOM_USERNAME}
  password: ${MY_CUSTOM_PASSWORD}
cases:
  - id: "profile-edit"
    name: "Edit User Profile"
    description: "Test editing user profile information"
    url: "https://myapp.com/account/profile"
    steps:
      - "Verify the profile page has loaded"
      - "Click the 'Edit Profile' button"
      - "Update the 'About Me' section with new text"
      - "Click the 'Save Changes' button"
      - "Verify success message appears"
      - "Reload the page and verify changes persisted"
  - id: "password-change"
    name: "Change Password"
    description: "Test changing user password"
    url: "https://myapp.com/account/security"
    steps:
      - "Navigate to the security settings page"
      - "Click on 'Change Password'"
      - "Enter current password and new password"
      - "Submit the form"
      - "Verify password change confirmation is displayed"

In this example, Testpilot will log in once, then run both test cases using the same authenticated session.

By properly configuring login credentials and URL, you can easily test authenticated sections of your application without repeatedly handling the login process in each test case.

Example: Testing Login Flow for a mobile app

For mobile apps, the login steps have to be more explicitly specified and tested, notably as done in step 2 below.

name: "Login Flow Test"
login:
  username: ${MY_CUSTOM_USERNAME}
  password: ${MY_CUSTOM_PASSWORD}
cases:
  - id: "perform-login"
    name: "Login to the app"
    description: "Test logging in to the app"
    steps:
      - "Click on the Login button on the top right"
      - "Login using username ${MY_CUSTOM_USERNAME} and password ${MY_CUSTOM_PASSWORD}"
      - "Verify the login was successful by confirming the user account's name is displayed on the top-left"
    platform_config:
      android_pkg: com.mymobileapp.android

If you are using a custom env-var for the password (i.e. other than TESTPILOT_PASSWORD) then you are encouraged to specify the top-level login.password field as well. This helps Testpilot handle the password string literal more securely.