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

> ## Agent Instructions
> Bach builds Windows installers from one bach.toml with the bach command: bach init, bach check, bach preview, bach build. Installs are per user and need no administrator rights by default. installer.scope = "machine" installs for every user after one Windows prompt. On Windows, run setup files with Start-Process -Wait -PassThru in PowerShell, and give signtool arguments that start with the word sign.

# bach test

> Install a setup file on a clean Windows in Windows Sandbox, start the app, remove it, and get a report of failures and leftover files.

`bach test` installs your setup file on a clean Windows, starts the app, removes it and tells you what went wrong and what was left behind. The sandbox is a fresh Windows every time and is thrown away at the end, so nothing is installed on your computer.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach build
bach test
bach test dist/Hello-Setup-1.4.0.exe --with samples
```

```console theme={"theme":{"light":"github-light","dark":"github-dark"}}
Testing Hello 1.4.0 in Windows Sandbox
  ok    Installed      exit code 0 in 0.7 s
  ok    Registered     Settings > Apps lists Hello 1.4.0
  ok    Files          12 of 12 files are in …\Programs\Hello
  ok    Uninstaller    uninstall.exe is in the install folder
  ok    Started        still running after 5 s
  ok    Removed        exit code 0 in 0.7 s
  ok    Left behind    nothing
```

| Option | Meaning |
| - | - |
| `FILE` | The setup file. Without it, the file `bach.toml` builds. |
| `--with IDS`, `--without IDS` | Options to install with, like the setup file's own flags. |
| `--launch SECONDS` | How long to leave the app running (default 5; `0` doesn't start it). |
| `--network` | Give the sandbox the network (off by default; an online installer needs it). |
| `--timeout MINUTES` | How long to wait for the report (default 20). |
| `--keep` | Leave the sandbox open afterwards. |
| `--dry-run` | Write the files the test would use and stop. Works without Windows Sandbox. |
| `--here` | Run the test on this computer instead of in Windows Sandbox. See below. Can't be combined with `--keep`. |

The exit code is `0` when every check passed and `1` otherwise. `--json` prints `passed`, `steps` and `left_behind`.

## Without Windows Sandbox

Windows Sandbox isn't on Windows Home, and it isn't on GitHub's Windows runners. `bach test --here` runs the same test, with the same checks and the same report, on the computer it is started on:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach test dist/Hello-Setup-1.4.0.exe --here
```

This installs the app for real and removes it again, so use it where that is harmless: a CI job or a virtual machine. If the app is already installed on the computer, the test fails at once with "already installed on this computer", before it changes anything, so your own copy is never the one it removes. The **Left behind** check compares folders and keys before and after, so run it where nothing else is installing at the same time. A setup file that asks for administrator rights needs a job that already has them (a GitHub runner does), because nobody can accept Windows' prompt.

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
- run: bach build
- run: bach test --here
```

> [!NOTE]
>
> Windows Sandbox comes with Windows 10 and 11 Pro, Enterprise and Education (not Home). Turn it on under "Turn Windows features on or off". A setup file that asks for administrator rights shows Windows' prompt inside the sandbox window; accept it there. A setup file with `[access]` needs a key a silent test can't type.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.