> ## Documentation Index
> Fetch the complete documentation index at: https://jetify-dependabot-npm-and-yarn-npm-and-yarn-387f502f5a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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[​](#setting-login-credentials "Direct link to Setting Login Credentials")

Testpilot uses environment variables to securely manage your login credentials:

```bash theme={null}
# 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[](#configuring-custom-environment-variables-for-login "Direct link to 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:

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

## Configuring Login URL [​](#configuring-login-url "Direct link to Configuring Login URL")

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

```yaml theme={null}
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[​](#how-authentication-works-for-websites "Direct link to 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[​](#example-testing-authenticated-features "Direct link to Example: Testing Authenticated Features in a Website")

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

```yaml theme={null}
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[](#example-testing-login-flow-for-a-mobile-app "Direct link to 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.

```yaml theme={null}
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.