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

# Test Execution Environments

> Understand how Tusk runs your unit tests

## Overview

A test execution environment is a sandboxed environment where Tusk runs the tests it generates. Think of it as a Docker container specifically configured for your project's testing needs.

<Info>
  Test execution environments are **fully managed by Tusk**. We handle:

  * Infrastructure and resource allocation
  * Initial configuration during automated setup
  * Ongoing maintenance as your project evolves

  You can view the configuration at any time and request updates if needed.
</Info>

## How It Works

When Tusk generates tests for a PR, it:

1. Spins up an isolated sandbox using your test execution environment
2. Checks out your code at the PR's commit
3. Runs setup scripts to install dependencies
4. Uses test and lint scripts to ensure all generated tests are working and conforming to your codebase's standards
5. Reports results back to your PR

## Setting Up Test Environments

Upon successful GitHub/GitLab authorization, navigate to the [Unit Tests](https://app.usetusk.ai/app/unit-tests/repos) page and click **Set up** on the repo you want to configure.

<Steps>
  <Step title="Analyze your repository">
    If you haven't already, click **Analyze Repository** Tusk examines your codebase to identify directories containing unit tests, testing frameworks, CI/CD configuration, and potential environment variables needed.

    This typically takes 2-4 minutes.
  </Step>

  <Step title="Review detected test environments">
    After analysis, you'll see a list of potential test environments. For each one, Tusk shows prerequisites:

    * Directory path (for monorepos with multiple services)
    * Test framework detected
    * CI status - whether tests currently run in CI
    * Coverage support - whether Tusk can collect coverage data

    Click **Set up** on any environment you want to configure.
  </Step>

  <Step title="Provide environment variables (if detected)">
    If Tusk detects that environment variables may be required (like NPM tokens for private packages), you'll be prompted before setup begins.

    You can:

    * Provide values now to ensure setup succeeds on the first try
    * Skip for now (Tusk will attempt setup without them and ask again if needed)
  </Step>

  <Step title="Wait for configuration">
    Tusk creates your test execution environment by:

    1. Creating a Dockerfile (or Docker Compose for projects needing databases/services)
    2. Writing setup scripts to install dependencies
    3. Writing test scripts configured for your framework
    4. Verifying everything works by running your tests
    5. Iterating if any issues are found

    This typically takes 6-10 minutes. You can leave the page and return later - setup continues in the background.
  </Step>

  <Step title="Answer questions (if needed)">
    During setup, Tusk may ask clarifying questions about your configuration:

    * Which test command to use if multiple are available
    * How to handle specific dependencies
    * Confirmation of environment variable requirements

    If you see a **"Needs Input"** status, click on the environment to answer the question.
  </Step>

  <Step title="Configuration complete">
    Once verified, your test execution environment is ready. Tusk will automatically run tests on new PRs and maintain the environment as your project evolves.
  </Step>
</Steps>

<Info>
  **Need to make changes?** You can update your test execution environment(s) at any time. Just describe what you'd like to change and Tusk will modify and re-verify the configuration.
  See below for context.
</Info>

***

## Configuration Components

Each test execution environment consists of several components that Tusk configures automatically during setup.

### Environment Definition

You'll have either a **Dockerfile** or a **Docker Compose** configuration depending on your project's needs.

**Dockerfile** - For most projects where tests only need the application runtime and mock external services.

**Docker Compose** - For projects where tests need real service dependencies (databases, Redis, etc.).

Tusk analyzes your repository and CI configuration to automatically determine which approach is best for your project.

### Scripts

| Script       | Purpose                                             |
| ------------ | --------------------------------------------------- |
| **Setup**    | Installs dependencies and prepares the environment  |
| **Test**     | Runs tests for a specific file                      |
| **Lint**     | (Optional) Runs formatting/linting and build checks |
| **Coverage** | (Optional) Collects test coverage data              |

### Configuration Settings

| Setting             | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **Test Framework**  | The testing framework detected                          |
| **App Directory**   | For monorepos, the subdirectory containing your service |
| **Test File Regex** | Pattern for matching test files in your codebase        |

## Viewing Your Configuration

To view an existing test execution environment:

1. Go to the **Unit Tests** page
2. Click on your repository
3. Select the **Test Execution Environments** tab
4. Click on an environment, then select the **Configuration** tab

You can view:

* The complete Dockerfile or Docker Compose file
* All setup, test, lint, and coverage scripts
* Environment variables (non-secret values only)
* Test file pattern and other settings

## Updating Configuration

If you need to modify your test execution environment:

1. Navigate to the environment in the Tusk UI
2. Click **Update**
3. Describe what you'd like to change
4. Tusk will update and re-verify the configuration

Common reasons to update:

* Adding new system dependencies
* Changing test commands or flags
* Enabling coverage collection
* Adding support for new services (databases, caches)
* Fixing issues with environment setup

<Info>
  Tusk verifies updates by running your tests, so you'll know immediately if the changes work.
</Info>

## Environment Variables

Test environments often need environment variables. Some examples include:

* NPM tokens for private packages
* Database passwords or connection strings
* Third-party service credentials

### Managing Environment Variables

1. Go to **Repository Settings > Environment Variables**
2. Click **Add Variable**
3. Enter the key, value, and mark as "Secret" if sensitive
4. Variables are automatically available in all test environments for that repo

<Warning>
  Never commit secrets to your repository. Use Tusk's environment variables feature instead - secrets are encrypted and never exposed in logs.
</Warning>

### When Tusk Asks for Variables

During setup or updates, Tusk may detect that environment variables are needed. You'll see a prompt asking for specific variables with context about why they're needed.

You can:

* Provide the values now to ensure setup succeeds on the first try
* Skip for now - setup continues and Tusk will ask again if tests fail due to missing variables

## Multiple Environments (Monorepos)

For monorepos with multiple services, you can have separate test execution environments - one per service directory (e.g., `packages/api`, `packages/web`). Each environment has its own Dockerfile and scripts, can use different test frameworks, and runs independently.

During repository analysis, Tusk identifies each testable directory and lets you set them up individually.

## Resources and Performance

Tusk automatically allocates and manages resources for your test environment. If you're experiencing slowdowns or timeout issues, contact [support@usetusk.ai](mailto:support@usetusk.ai) to discuss resource tuning.

## FAQs

<AccordionGroup>
  <Accordion title="What happens if test environment setup fails?">
    If setup encounters an issue it can't resolve automatically, you'll see a **"Failed"** status with details about what went wrong. You can:

    1. Review the error - Click into the environment to see the specific failure
    2. Provide missing information - Often failures are due to missing environment variables or unclear configuration
    3. Retry setup - After addressing the issue, click **Retry** to start again
    4. Contact support - For complex issues, reach out to [support@usetusk.ai](mailto:support@usetusk.ai)
  </Accordion>

  <Accordion title="How do I update an existing test environment configuration?">
    You can update any test execution environment at any time:

    1. Go to the **Unit Tests** page and click on your repository
    2. Select the **Test Execution Environments** tab
    3. Click on the environment you want to modify
    4. Click **Update** and describe what you'd like to change

    Tusk will update the configuration and re-verify that tests still pass.
  </Accordion>

  <Accordion title="Can I have multiple test environments for a monorepo?">
    Yes! During repository analysis, Tusk identifies each directory that contains tests. You can set up separate test execution environments for each service or package in your monorepo.

    Each environment has its own Dockerfile, scripts, and configuration - they run independently when Tusk generates tests for changes in that directory.
  </Accordion>
</AccordionGroup>