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

# Device Presets

> Configure browser sessions with predefined device settings

Device presets allow you to configure browser sessions with predefined device settings, making it easy to test your application across different device configurations. When using device presets, you can simulate specific devices with their viewport sizes, user agents, and other device-specific settings.

## Overview

Device presets let you configure browser sessions with predefined device settings, making it easy to test your application across different device configurations. Use device presets to:

* Test responsive design across mobile, tablet, and desktop layouts
* Test localization with different locales and timezones (e.g., EU vs US users)
* Test accessibility preferences like dark mode and reduced motion
* Test browser-specific behavior (e.g., Safari mobile quirks)
* Add custom authentication headers for staging environments

## When to Create Separate Presets

Create separate device presets when you need to:

| Use Case                       | Example                   | What to Configure       |
| ------------------------------ | ------------------------- | ----------------------- |
| Test responsive design         | Mobile vs desktop layouts | Device type, resolution |
| Test localization              | EU vs US users            | Locale, timezone        |
| Test accessibility preferences | Dark mode, reduced motion | Accessibility settings  |
| Test browser-specific behavior | Safari mobile quirks      | User agent, device type |
| Add authentication headers     | Staging with basic auth   | Custom headers          |

See [Applications and Environments](/core-concepts/applications-and-environments) for how device presets fit into the overall test configuration hierarchy.

## Available Settings

Device presets include the following settings:

* **Device Type**: Choose between Desktop, Tablet, or Mobile configurations
* **Resolution**: Each device type comes with predefined viewport sizes
* **Locale**: Set the browser's language and region settings (e.g., en-US, sv-SE)
* **Timezone**: Configure the device's timezone (e.g., Europe/Stockholm)
* **Custom Headers**: Add custom HTTP headers for special testing requirements

## Managing Device Presets

### Creating a Preset

<Steps>
  <Step title="Navigate to Device Presets">
    Go to [**Settings → Device
    Presets**](https://app.qa.tech/current-project/settings/device-presets)
  </Step>

  <Step title="Create New Preset">Click the "Create Device Preset" button</Step>

  <Step title="Configure Settings">
    Fill in the required settings: - Name your preset - Select a device type
    (Desktop/Tablet/Mobile) - Configure locale and timezone - Optionally
    override the default resolution - Optionally override the default user agent
  </Step>

  <Step title="Add Custom Headers (Optional)">
    If needed, add custom HTTP headers: - Click "Custom Headers" - Select a
    header name or type your own - Enter the header value - Click the plus icon
    to add more
  </Step>

  <Step title="Set as Default (Optional)">
    Toggle "Set as default preset" if you want this to be the project default
  </Step>

  <Step title="Save">Click "Create" to save your preset</Step>
</Steps>

### Resolution Settings

Each device type comes with a default resolution:

* **Desktop**: 1280×800 (recommended)
* **Tablet**: 768×1024
* **Mobile**: 375×667

You can override these defaults using the resolution toggle in the preset configuration.

> **Note**: Using resolutions larger than 1280×800 may result in slower test execution. Our testing model is optimized for the default desktop resolution (1280×800) to provide the best balance of coverage and performance.

### User Agent

Each device type comes with an appropriate default user agent. You can override this using the user agent toggle if needed for specific testing scenarios.

### Custom Headers

You can add custom HTTP headers to be sent with **all requests** from this device (navigation, resources, API calls, redirects). This is useful for:

* Adding authentication headers (e.g., `Authorization: Bearer token`)
* Bypassing bot protection (e.g., `X-Vercel-Code: your-code`)
* Adding API keys (e.g., `X-API-Key: your-key`)
* Custom request identification

**How to add headers:**

1. Expand the "Custom Headers" accordion section
2. Select a header name from the autocomplete dropdown (47 common headers available) or type your own
3. Enter the header value
4. Click the plus icon (+) to add the header
5. Repeat to add multiple headers
6. Click the trash icon to remove a header

**Header validation:**

* Header names must follow RFC 7230: letters, numbers, hyphens, underscores, and periods only (e.g., `X-API-Key`, `Authorization`)
* Header values can contain printable ASCII characters
* Both name and value are validated before saving

<Warning>
  **CORS Considerations:** Custom headers may cause CORS errors if the target server doesn't include them in `Access-Control-Allow-Headers`. This could prevent requests that would otherwise succeed.
</Warning>

### Default Presets

Each project can have one default device preset. When set, this preset will be used for all tests unless overridden by higher-priority settings. See [Priority Order](#priority-order) for the complete hierarchy of how device presets are selected.

## Using Device Presets in AI Chat

You can discover and work with device presets through the [AI Chat Assistant](/core-concepts/ai-chat-assistant) using natural language. The assistant can show you available presets and help you create or run tests with specific device configurations.

**Example: Creating tests for mobile**

Say you want to create tests that run on mobile devices. Simply ask:

> "Create a test for the checkout flow on mobile"

The assistant will:

1. Show you available mobile device presets
2. Ask which specific preset you'd like to use
3. Create the test configured with the selected device preset

**Example: Running tests with a different device**

You can also override device presets when running existing tests:

> "Run the login test on an iPhone"

The assistant will show available mobile presets and run the test with your selected device configuration, overriding the test's default preset for that run.

**More example queries:**

* "What device presets do I have?"
* "Show me all mobile presets"
* "Can I test on tablet?"
* "Create checkout tests for mobile and desktop"

This makes it easy to explore your device options and work with device-specific testing without navigating through settings pages. Learn more about chat capabilities in the [AI Chat Assistant documentation](/core-concepts/ai-chat-assistant).

## Priority Order

Device preset selection follows this priority order:

1. AI Chat runtime override (when specified)
2. Test case setting (configured when editing a test case)
3. Test plan setting (see [Test Plans](/core-concepts/test-plans))
4. Project default preset
5. QA Tech default preset (fallback)

## Integration with Test Plans

Device presets can be configured at the test plan level, allowing you to run the same test cases with different device configurations. This is particularly useful for:

* Testing responsive design across multiple devices
* Verifying functionality on specific device types
* Running the same test plan with different locale/timezone settings

When a test plan has a device preset configured, it takes precedence over project defaults but can still be overridden by individual test case settings. Learn more about test execution and configuration in our [Test Plans documentation](/core-concepts/test-plans).

### Setting Device Presets in Test Plans

<Steps>
  <Step title="Open Test Plan Settings">
    Navigate to your test plan and click "Settings"
  </Step>

  <Step title="Select Device Preset">
    Choose a device preset from the dropdown menu
  </Step>

  <Step title="Save Changes">
    Click "Save" to apply the device preset to your test plan
  </Step>
</Steps>

All test runs initiated from this test plan will now use the selected device preset unless overridden by test case settings.

### Multi-Device Testing Strategy

To test the same functionality across different devices, you have two options:

**Option 1: Separate Test Plans**

1. Create device presets for each target device (e.g., "iPhone 14", "Galaxy Tab", "Desktop Chrome")
2. Create separate test plans that use different device presets
3. Run the appropriate test plan in your pipeline or schedule

**Option 2: API Overrides**
Override device presets per-run via API using the `devicePresetShortId` parameter in the `applications` array. This allows you to test different device configurations without creating multiple test plans. See [Start Run API](/api-reference/start-run) for details.

The [GitHub App](/configuration/github-app) can automatically select device presets based on PR content - for example, testing on mobile when a PR mentions "responsive design".

## Accessibility Emulation

Test how your app responds to user accessibility preferences:

| Setting            | Values                           | Purpose                       |
| ------------------ | -------------------------------- | ----------------------------- |
| **Color Scheme**   | `light`, `dark`, `no-preference` | Test dark mode                |
| **Forced Colors**  | `active`, `none`                 | Test high contrast mode       |
| **Reduced Motion** | `reduce`, `no-preference`        | Test with animations disabled |

Configure in Advanced Settings when creating/editing device presets.

<Note>
  These settings **emulate user preferences**. For checking WCAG violations, see [Accessibility Issues](/core-concepts/issues#accessibility-issues).
</Note>

## Best Practices

1. **Use Project Defaults**: Set a default device preset at the project level for consistent testing
2. **Match Target Devices**: Choose presets that match your target audience's devices
3. **Test Responsiveness**: Create presets for different device types to verify responsive design
4. **Document Custom Presets**: Add clear names and descriptions to custom presets
5. **Keep it Simple**: Use the default resolution and user agent unless you have specific requirements

## Restrictions

* Maximum viewport size: 1280x1024
* Device presets must use one of the three device types (Desktop/Tablet/Mobile)
* Each project can have only one default preset

## Troubleshooting

If you encounter issues with device presets:

1. **Preset Not Applied**: Check the priority order to understand which preset is being used
2. **Resolution Issues**: Make sure the override toggle is enabled if you want to use custom resolutions
3. **Custom Headers**: Verify header names and values are properly formatted
4. **Default Not Working**: Confirm only one preset is set as default in the project

## Technical Notes

* Device presets are stored as snapshots in test runs for reproducibility
* Default configurations are optimized for common testing scenarios
* Custom headers are preserved across test runs
* Locale and timezone settings affect date/time handling in tests
* Device preset information is stored in test results and can be used for analysis

## Related Documentation

* [Test Plans](/core-concepts/test-plans) - Configure device presets per test plan
* [Applications and Environments](/core-concepts/applications-and-environments) - How device presets fit into the test configuration hierarchy
* [AI Chat Assistant](/core-concepts/ai-chat-assistant) - Override device presets at runtime
* [GitHub App](/configuration/github-app) - Automatic device testing for PRs