Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,14 @@ vstest.console (entry point)
| Release config | `./build.cmd -c Release -pack` | `./build.sh -c Release --pack` |
| Unit tests | `./test.cmd` | `./test.sh` |
| Specific tests | `./test.cmd -projects <pattern>` | `./test.sh -p <pattern>` |
| Several test projects | `./test.cmd -projects "test\A\A.csproj;test\B\B.csproj"` | `./test.sh -p "test/A/A.csproj;test/B/B.csproj"` |
| Smoke tests | `./test.cmd -projects smoke` | `./test.sh -p smoke` |
| Single test by name | `./test.cmd -bl -c release /p:TestRunnerAdditionalArguments="'--filter TestName'"` | Similar |
| Single test by name | `./test.cmd -bl -c release /p:TestRunnerAdditionalArguments="--filter TestName"` | Similar |

CI builds use `-c Release`. Always build with Release config before submitting PRs.

The `.cmd` wrappers pass arguments to PowerShell literally. See [Wrapper scripts pass arguments literally](#wrapper-scripts-pass-arguments-literally) before changing one.

## Test Structure

Test projects mirror source projects under `test/`:
Expand All @@ -63,6 +66,27 @@ Test categories: Unit (fast, default), Smoke (P0 e2e), Acceptance (full e2e with

## Known Gotchas

### Wrapper scripts pass arguments literally

`build.cmd`, `test.cmd`, `restore.cmd`, `open-vs.cmd`, `open-code.cmd`, and `eng/RestoreInternal.cmd` invoke PowerShell with `-File`, so everything after the script path reaches `eng/build.ps1` as a literal argument.

They previously used `-command "& """%~dp0eng\Build.ps1""" %*"`, which spliced `%*` into a string that PowerShell then parsed as source code. That caused two problems, both fixed:

- `;` in an argument became a statement separator. `./test.cmd -projects "test\A\A.csproj;test\B\B.csproj"` ran `Build.ps1 -projects test\A\A.csproj` and then executed `test\B\B.csproj` as its own statement. On Windows `.csproj` is file-associated with Visual Studio, so every entry after the first opened a full IDE. Three agents ran this form at the same time and opened eighteen instances of Visual Studio.
Comment thread
nohwnd marked this conversation as resolved.
Resolved
- Exit codes collapsed to `1`. `eng/build.ps1` ends with `exit $LastExitCode` to forward the real code, but `-command` discarded it, so `8` (filter matched no tests) and every other code arrived as `1`.

Use `-File` in any new `.cmd` wrapper. Do not switch back to `-command`.

Because arguments are no longer re-parsed, MSBuild properties need one level of quoting instead of two:

```
./test.cmd -bl -c release /p:TestRunnerAdditionalArguments="--filter TestName"
```

`eng/common/*` comes from Arcade and still uses `-command`. Do not edit those files here; fix them in the Arcade repository.

Independent of the wrappers: never run a `.csproj` or `.sln` path as a command. The path is always an argument, as in `dotnet test <path>.csproj`.

### Binding Redirects

Bumping a `netstandard2.0` package cascades: transitive deps need binding redirects in ALL three app.configs (`vstest.console/app.config`, `testhost.x86/app.config`, `datacollector/app.config`). Miss one and you get `FileLoadException` in net462 DTA hosts.
Expand Down
2 changes: 1 addition & 1 deletion build.cmd
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
@echo off
powershell -ExecutionPolicy ByPass -NoProfile -command "& """%~dp0eng\Build.ps1""" -restore -build %*"
powershell -ExecutionPolicy ByPass -NoProfile -File "%~dp0eng\Build.ps1" -restore -build %*
Comment thread
nohwnd marked this conversation as resolved.
Resolved
exit /b %ErrorLevel%
2 changes: 1 addition & 1 deletion eng/RestoreInternal.cmd
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
@echo off
powershell -ExecutionPolicy ByPass -NoProfile -command "& """%~dp0\common\build.ps1""" -build -restore %*"
powershell -ExecutionPolicy ByPass -NoProfile -File "%~dp0common\build.ps1" -build -restore %*
2 changes: 1 addition & 1 deletion open-code.cmd
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
@echo off
powershell -ExecutionPolicy ByPass -NoProfile -command "& """%~dp0eng\build.ps1""" -vscode %*"
powershell -ExecutionPolicy ByPass -NoProfile -File "%~dp0eng\build.ps1" -vscode %*
2 changes: 1 addition & 1 deletion open-vs.cmd
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
@echo off
powershell -ExecutionPolicy ByPass -NoProfile -command "& """%~dp0eng\build.ps1""" -vs %*"
powershell -ExecutionPolicy ByPass -NoProfile -File "%~dp0eng\build.ps1" -vs %*
2 changes: 1 addition & 1 deletion restore.cmd
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
@echo off
powershell -ExecutionPolicy ByPass -NoProfile -command "& """%~dp0eng\Build.ps1""" -restore %*"
powershell -ExecutionPolicy ByPass -NoProfile -File "%~dp0eng\Build.ps1" -restore %*
Comment thread
nohwnd marked this conversation as resolved.
Resolved
2 changes: 1 addition & 1 deletion test.cmd
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
@echo off
if not defined MSBUILDTERMINALLOGGER set MSBUILDTERMINALLOGGER=off
powershell -ExecutionPolicy ByPass -NoProfile -command "& """%~dp0eng\Build.ps1""" -test %*"
powershell -ExecutionPolicy ByPass -NoProfile -File "%~dp0eng\Build.ps1" -test %*
Comment thread
nohwnd marked this conversation as resolved.
Resolved
exit /b %ErrorLevel%