> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autonoma.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Your Application

> Learn how to add your application to Autonoma and configure authentication for testing web and mobile apps.

## Authentication Options

Autonoma supports multiple authentication methods. Choose the one that matches your application:

<CardGroup cols="2">
  <Card title="Email and Password" icon="user" href="#email-and-password" cta="Most common authentication method with username/password" />

  <Card title="Magic Link" icon="envelope" href="#magic-link" cta="Passwordless authentication via email links" />

  <Card title="Header or Cookie Bypass" icon="key" href="#header-or-cookie-bypass" cta="Fastest method requiring development team support" />

  <Card title="IP Whitelisting" icon="lock" href="#ip-whitelisting" cta="Additional security layer for restricting access" />
</CardGroup>

## Why Application Configuration Matters

Before you can test your application with Autonoma, you need to set it up properly. This involves two key steps:

1. **Adding your application** to Autonoma (telling it what to test)
2. **Configuring authentication** (how your tests will access protected features)

Think about it: if your application requires users to log in (and most do), your tests need to be able to log in too. Otherwise, they can only test your login page!

This guide walks you through both steps, from adding web/mobile applications to setting up various authentication methods.

## Step 1: Adding Your Application

To start running tests, you first need to add the application (either web or mobile) you plan to test.

### For Web Applications

1. **Add a Name**\
   Provide a **name** for the web application. This helps you easily identify it in your list of available applications.

2. **Enter the URL**\
   Add the **URL** where the web application is hosted. This could be a public-facing URL or an internal testing environment URL.

3. **Set an Environment Tag**\
   Assign an **environment tag** to indicate where the web app is running. Common tags include **Prod**, **Staging**, **QA**, but you can also create custom tags specific to your business needs (e.g., **Dev**, **Beta**, etc.).

### For Mobile Applications

1. **Add a Name**\
   Provide a **name** for the mobile application so you can easily identify it.

2. **Upload the Application File**\
   Upload the mobile app file (.apk for Android, .app for iOS) that you want to test. This is the app version you'll be interacting with during your tests.

3. **Add a Version Tag**\
   Specify the **version** of the mobile app, such as **1.x**, **2.x**, etc., to distinguish between different releases or iterations.

![Applications setup demonstration](https://cdn.autonoma.app/images/applications.gif)

Once you've uploaded the application (and version), it's now ready to be used! You can immediately start building and running tests over it. This allows you to test web and mobile apps effectively by simulating user interactions, verifying functionality, and ensuring quality across different versions and environments.

## Step 2: Configuring Authentication

Now that your application is added, you need to configure how your tests will authenticate. Let's identify what type of authentication your application uses.

## Email and Password

This is the recommended approach if your application uses traditional username/password login.

#### How It Works

Your tests will:

1. Navigate to your login page
2. Enter the email address
3. Enter the password
4. Click the login button
5. Verify successful login

#### Step-by-Step Setup

**Step 1: Create a Test Account**

Before setting up Autonoma, create a dedicated test account in your application:

**Best practices for test accounts**:

* Use a dedicated email: `autonoma-test@yourcompany.com`
* Use a secure but memorable password
* Give it appropriate permissions (usually similar to a regular user)
* Don't use a real customer account
* Document the credentials securely

**Why a dedicated account?**

* Won't interfere with real user data
* Can be reset/cleaned up between test runs
* Makes it clear which traffic is from tests

**Step 2: Configure in Autonoma**

1. Log into Autonoma
2. Go to your application settings
3. Select "Email and Password" as your authentication method
4. Enter your test account credentials

**Important**: Autonoma stores credentials securely and encrypted.

**Step 3: Create a Login Test**

Create a reusable login test that other tests can reference:

```
Test: "Login - Test account authentication"

1. Navigate to login page
2. Type test email in email field
3. Type test password in password field
4. Click "Sign In" button
5. Wait until: Dashboard appears
6. Verify: User is logged in (check for profile icon/name)
```

**Step 4: Use Variables for Credentials**

Instead of hard-coding credentials in every test, use Autonoma's **Variables** feature:

1. Go to Variables section in your Autonoma project

2. Create variables:
   * `TEST_EMAIL` = `autonoma-test@yourcompany.com`
   * `TEST_PASSWORD` = `your-secure-password`

3. In your tests, reference variables:
   * "Type `{{variable:TEST_EMAIL}}` in email field"
   * "Type `{{variable:TEST_PASSWORD}}` in password field"

**Benefits of variables**:

* Change credentials in one place, updates all tests
* Makes tests more readable
* Easier to manage multiple test accounts
* Can have different credentials for staging vs. production

#### Common Issues and Solutions

**Issue**: Test fails at login every time

**Possible causes**:

* Credentials are incorrect (typo in email/password)
* Login page has changed
* Rate limiting is blocking automated logins
* CAPTCHA is appearing

**Solutions**:

* Verify credentials work manually
* Update test if UI changed
* Contact your dev team about whitelisting Autonoma's IP
* Ask dev team to disable CAPTCHA for test accounts

**Issue**: Login works but session expires quickly

**Solution**:

* Ask your dev team to extend session timeout for test accounts
* Or create a "re-login" test step you can reuse when sessions expire

## Magic Link

Magic links are special URLs sent via email that log users in when clicked. Testing these requires accessing email programmatically.

![Explaining how to login with magic link in Autonoma](https://cdn.autonoma.app/interaction-gifs/interaction-email-generator.gif)

### How It Works

Autonoma provides special interactions that let you:

1. Generate a temporary email address that can receive emails
2. Input the generated email on the login form
3. Request a magic link (sent to that email)
4. Wait for the email to be sent and received
5. Extract the magic link from the email
6. Navigate to the extracted URL to complete login

### Step-by-Step Setup

**Step 1: Create a Magic Link Login Test**

Here's how to structure your test:

```
Test: "Login - Magic link authentication"

1. Navigate to login page

2. Add prompt: "Generate an email address for extracting information"
   (This uses email-retriever-generator to create a new email each time)
   → System generates: temp-12345@autonoma-test.com

3. Type the generated email {{key:generated_email}} into the email input field

4. Click "Send Magic Link" (or similar button)

5. Wait for 3-5 seconds to allow the email to be sent and received

6. Add prompt: "Using the generated email, retrieve the magic link to login to [your-app-domain]"
   (This extracts the magic link from the received email)
   → Information is stored in key: email_retrieved_information

7. Add prompt: "Go to URL {{key:email_retrieved_information}}"
   (This navigates to the extracted magic link)

8. Wait until: Dashboard or home page appears

9. Verify: User is logged in
```

#### Common Issues and Solutions

**Issue**: Email doesn't arrive

**Possible causes**:

* Email generation failed
* Your app doesn't recognize the generated email domain
* Email is caught in spam filters

**Solutions**:

* Check that the email address was actually generated (look at test output)
* Ask dev team to whitelist `@autonoma-test.com` domain
* Add a wait: "Wait until email arrives" with longer timeout

**Issue**: Can't extract the magic link

**Possible causes**:

* Email format changed
* Link is encoded or hidden
* Multiple links in email

**Solutions**:

* Be more specific in your retrieval prompt
* Ask dev team for the email template structure
* Look at a real magic link email for reference

## Header or Cookie Bypass

This is the fastest and most reliable approach if your development team can support it. Instead of going through the login flow, you pass special authentication credentials directly via HTTP headers or cookies.

#### Benefits

* **Fast**: No login flow needed, tests start immediately
* **Reliable**: No risk of login UI changes breaking tests
* **Simple**: One configuration, works for all tests
* **Clean traffic**: Easy to identify and filter test traffic

**What You Need from Your Dev Team**

Ask your developers to implement one of these:

#### Option A: Authentication Header

**Request to dev team**:
"Can you add support for a special authentication header that bypasses login for our Autonoma tests?"

**Example implementation** (they'll understand):

```
If request has header: X-Test-Auth: autonoma-test-token-12345
Then: Authenticate as test user
```

**What you'll configure in Autonoma**:

* Header name: `X-Test-Auth`
* Header value: `autonoma-test-token-12345`

#### Option B: Authentication Cookie

**Request to dev team**:
"Can you add support for a special authentication cookie that bypasses login for our Autonoma tests?"

**Example implementation**:

```
If request has cookie: test_auth=autonoma-test-token-12345
Then: Authenticate as test user
```

**What you'll configure in Autonoma**:

* Cookie name: `test_auth`
* Cookie value: `autonoma-test-token-12345`

**Step 1: Coordinate with Your Dev Team**

1. Share this guide with your development team
2. Ask them to implement either header or cookie bypass
3. Get the exact header/cookie name and value they implemented
4. Confirm it works in staging/test environments

**Step 2: Configure in Autonoma**

1. Go to your application settings in Autonoma
2. Select "Authentication Header" or "Authentication Cookie"
3. Enter the header/cookie name
4. Enter the header/cookie value
5. Save configuration

**Step 3: Test It**

Create a simple test that verifies it works:

```
Test: "Verify authentication bypass works"

1. Navigate to dashboard (usually requires login)
2. Verify: Dashboard loads successfully
3. Verify: User information is displayed
```

If this test passes without any login steps, your bypass is working correctly!

#### Security Considerations

**Your dev team might worry about security**. Reassure them:

1. **Only enable in non-production environments** (staging, test, dev)
2. **Use a secret token** that's not easily guessable
3. **Combine with IP whitelisting** (Option 5) for extra security
4. **Log bypass usage** so you can monitor it

This is a standard practice for automated testing and is safe when configured properly.

## IP Whitelisting

IP whitelisting means your application only allows access from specific IP addresses. This is often used in addition to other authentication methods.

#### Autonoma's Static IP

Autonoma uses a static IP address for all test execution:

```
3.148.127.74
```

#### Step-by-Step Setup

**Step 1: Provide IP to Your Dev Team**

Send this message to your development or DevOps team:

```
Hi team,

We're setting up automated testing with Autonoma. Please whitelist this IP address in [staging/production]:

IP: 3.148.127.74
Purpose: Autonoma automated testing
Environment: [specify which environments]

Let me know once this is configured. Thanks!
```

**Step 2: Verify Whitelisting Works**

Once your team confirms the IP is whitelisted, test it:

1. Create a simple test that accesses your application
2. Run the test
3. Verify it can access your app without IP-related blocks

## Choosing the Right Authentication Strategy

Here's a decision guide:

### Use Email/Password When:

* ✅ Your app uses traditional login
* ✅ You want the simplest setup
* ✅ You don't need maximum speed
* ✅ Your team can't implement bypass headers

### Use Magic Link When:

* ✅ Your app uses passwordless authentication
* ✅ You're comfortable with email automation
* ✅ Your app supports temporary email domains

### Use Header/Cookie Bypass When:

* ✅ You want the fastest tests possible
* ✅ Your dev team can support it
* ✅ You test frequently
* ✅ You want maximum reliability

### Use IP Whitelisting When:

* ✅ Your app needs IP-based security
* ✅ You want to restrict test access
* ✅ You're using it alongside another method

### Recommended Combinations

**Best for most teams**:
Email/Password + Variables

**Best for speed**:
Header Bypass + IP Whitelisting

**Best for passwordless apps**:
Magic Link + IP Whitelisting

## Next Steps After Configuration

Once your application is configured:

1. ✅ **Create a login test** (if using email/password or magic link)
2. ✅ **Verify it works** by running a simple test
3. ✅ **Document your setup** for your team
4. ✅ **Start creating feature tests** (now that you can access your app)
5. ✅ **Set up CI/CD integration** (Integrate With CI/CD →)

## Troubleshooting Common Issues

### Tests can't access the application

**Check**:

* Is IP whitelisting configured correctly?
* Is the application URL correct?
* Is the environment (staging/production) accessible?

### Login tests keep failing

**Check**:

* Are credentials correct?
* Has the login UI changed?
* Is there a CAPTCHA appearing?
* Is rate limiting blocking automated logins?

### Magic links aren't working

**Check**:

* Is the email domain whitelisted?
* Is the email actually being sent?
* Is the link extraction prompt specific enough?
* Are you waiting long enough for the email to arrive?

### Header/cookie bypass not working

**Check**:

* Did dev team actually implement it?
* Is the header/cookie name exactly correct (case-sensitive)?
* Is the header/cookie value exactly correct?
* Is it enabled in the environment you're testing?

## Key Takeaways

1. **Application setup requires two steps**: adding the app and configuring authentication
2. **Email/password is simplest** but requires maintaining test accounts
3. **Magic links are possible** using Autonoma's email interactions
4. **Header/cookie bypass is fastest** and most reliable with dev team support
5. **IP whitelisting adds security** and works well with other methods
6. **Use variables** to manage credentials across all tests

## What's Next

With your application configured, you're ready to integrate Autonoma into your development workflow. The next guide covers CI/CD integration—running your tests automatically whenever code changes.

***