> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/automation/tests.md).

# Tests

Run and review Pester test suites directly within PowerShell Universal, tracking historical results for individual test files and full test runs.

> This feature requires a [license](/powershell-universal/licensing.md).

PowerShell Universal integrates with [Pester](https://pester.dev/) to run test suites from your repository and retain their results. Use **Run > Tests** to discover test files, start runs, schedule them, and review historical outcomes.

## Test discovery

PowerShell Universal scans the repository recursively for files named `*.tests.ps1`. Discovered files appear on the **Test Files** tab. Create or edit the files from **Build > Scripts**, then refresh the test files when repository contents change.

Use the folder view to browse discovered test files by their repository folders. Select a folder to limit the file list to that location, or select **Tests** to return to all files.

## Prepare an execution environment

Install Pester in every execution environment that will run tests. A run fails when `Invoke-Pester` is unavailable in the selected environment.

Environment variables configured for the selected execution environment are available while Pester runs. This lets tests use configuration values without hard-coding them in test files. Treat sensitive values as secrets and retrieve them through the appropriate PowerShell Universal configuration.

## Run tests from the admin console

1. Go to **Run > Tests**.
2. Select **Run Test** for one file, or **Run All Tests** to run the discovered test files.
3. Choose the credential, execution environment, and computer or computer group to use.
4. Select **Run**. The run opens in the results view while it is queued or running.

You can run an individual test file, a repository folder, or a wildcard path. When a folder is selected, PowerShell Universal runs matching `*.tests.ps1` and `*.test.ps1` files beneath it.

## Run tests with PowerShell

Use `Invoke-PSUTest` to start a Pester run from a script, terminal, or automation workflow. Pass a path or a `TestFile` object.

```powershell
Invoke-PSUTest -Path '.\tests\api.tests.ps1'
```

Target a subset of Pester tests with tags, excluded tags, or full test names.

```powershell
Invoke-PSUTest -Path '.\tests\api.tests.ps1' `
    -Tag Smoke `
    -ExcludeTag Slow `
    -Test 'API returns 200'
```

By default, the cmdlet returns the newly created test-run record. Add `-Wait` to wait for a completed or failed run. `-Timeout` sets the wait limit in seconds and defaults to 300. Add `-IncludeSuite` to return both the test run and the parsed test-suite details.

```powershell
$result = Invoke-PSUTest -Path '.\tests\api.tests.ps1' -Wait -IncludeSuite
$result.TestRun
$result.TestSuite
```

Use `-Environment` when the tests require a particular execution environment.

## Schedule test runs

Create scheduled Pester runs from **Run > Tests** by selecting **Create Schedule**. Tests support simple, continuous, cron, and one-time schedules. Select the test path to run and the same run options used for other scheduled automation, including execution environment, credential, and computer settings.

Scheduled test paths are validated against the repository before they run. Keep paths within the repository and ensure that the referenced file, folder, or wildcard resolves to one or more test files.

## Review test results

Each test run records its status, start and end times, totals, failures, errors, skipped tests, and execution error details. PowerShell Universal writes Pester output in NUnit XML format and stores the parsed suite and test-case results so they remain available after the run finishes.

Open a test run from **Run > Tests > Test Results** to inspect the overall outcome and drill into suites and individual cases. Historical runs remain available for comparison and troubleshooting.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/powershell-universal/automation/tests.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.