Migrowanie z programu VSTest do Microsoft. Testing.Platform (MTP)

Z tego artykułu dowiesz się, jak przeprowadzić migrację z programu VSTest do MTP.

Ten artykuł koncentruje się na krokach migracji i mapowaniu argumentów.

Jeśli nadal musisz wybrać platformę, zacznij od omówienia platform testowych.

Jeśli potrzebujesz szczegółowego zachowania trybów dotnet test, odwołaj się do polecenia Testowanie za pomocą dotnet test.

Jeśli potrzebujesz pojedynczej listy opcji wiersza polecenia platformy i rozszerzeń, zobacz dokumentację opcji CLI MTP.

Wyrażanie zgody na korzystanie z protokołu MTP

Pierwszym krokiem migracji jest skorzystanie z protokołu MTP.

Dla wszystkich frameworków testowych dodaj <OutputType>Exe</OutputType> do wszystkich projektów testowych w rozwiązaniu. Następnie postępuj zgodnie ze wskazówkami specyficznymi dla platformy.

MSTest

Protokół MTP jest obsługiwany przez bibliotekę MSTest, począwszy od wersji 3.2.0. Zalecamy jednak zaktualizowanie do najnowszej dostępnej wersji MSTest.

Aby wyrazić zgodę, dodaj <EnableMSTestRunner>true</EnableMSTestRunner> pod elementem PropertyGroup w pliku Directory.Build.props.

NUnit

MTP jest obsługiwany przez NUnit3TestAdapter począwszy od wersji 5.0.0.

Aby wyrazić zgodę, dodaj <EnableNUnitRunner>true</EnableNUnitRunner> pod elementem PropertyGroup w pliku Directory.Build.props.

xUnit.net

MTP jest obsługiwane od wersji xunit.v3.

Aby wyrazić zgodę, dodaj <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner> pod elementem PropertyGroup w pliku Directory.Build.props.

dotnet test

Zgoda na zestaw .NET 9 SDK i jego wcześniejsze wersje

W .NET 9 zestawach SDK i starszych nie ma rodzimej obsługi protokołu MTP dla dotnet test. Obsługa jest oparta na infrastrukturze VSTest. Aby tego użyć, dodaj <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport> pod PropertyGroup w pliku Directory.Build.props.

Zgoda na korzystanie z zestawu .NET 10 SDK i nowszych wersji

Począwszy od zestawu SDK .NET 10, zapewnia się natywną obsługę MTP. Aby go użyć, należy określić moduł uruchamiający testy, jak Microsoft.Testing.Platform w global.json:

{
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}

Zaktualizuj wywołania dotnet test

Opcje dotnet test wiersza polecenia są podzielone na dwie kategorie: argumenty związane z kompilacją i powiązane z testami.

Argumenty związane z kompilacją nie mają znaczenia dla platformy testowej i w związku z tym nie muszą być aktualizowane dla nowej platformy. Argumenty związane z kompilacją są wymienione tutaj:

• -a|--arch <ARCHITECTURE>
• --artifacts-path <ARTIFACTS_DIR>
• -c|--configuration <CONFIGURATION>
• -f|--framework <FRAMEWORK>
• -e|--environment <NAME="VALUE">
• --interactive
• --no-build
• --nologo
• --no-restore
• -o|--output <OUTPUT_DIRECTORY>
• --os <OS>
• -r|--runtime <RUNTIME_IDENTIFIER>
• -v|--verbosity <LEVEL>

Mimo że --arch pozostaje opcją związaną z kompilacją, zastępuje architekturę wybraną przez program VSTest za pomocą polecenia RunConfiguration.TargetPlatform. Przekaż --arch do samego dotnet test, przed jakimkolwiek separatorem --.

Na przykład zmigruj to polecenie projektu VSTest:

dotnet test MyTests.csproj -c Debug -- RunConfiguration.TargetPlatform=x86 /Parallel

W przypadku zestawu SDK platformy .NET 10 i nowszych wersji użyj następującego polecenia MTP:

dotnet test --project MyTests.csproj -c Debug --arch x86

Zastąp x86 elementem x64, aby jako architekturę docelową ustawić x64. Domyślnie usługa MTP uruchamia moduły testowe równolegle, więc /Parallel nie wymaga zamiany. Aby ograniczyć równoległość na poziomie modułu, użyj polecenia --max-parallel-test-modules <NUMBER>.

Na przykład zastąp te cztery polecenia VSTest na poziomie rozwiązania:

dotnet test MySolution.sln -c Debug -- RunConfiguration.TargetPlatform=x86 /Parallel
dotnet test MySolution.sln -c Release -- RunConfiguration.TargetPlatform=x86 /Parallel
dotnet test MySolution.sln -c Debug -- RunConfiguration.TargetPlatform=x64 /Parallel
dotnet test MySolution.sln -c Release -- RunConfiguration.TargetPlatform=x64 /Parallel

W przypadku zestawu .NET 10 SDK i nowszych wersji użyj macierzy na poziomie projektu:

$testProjects = @("tests/A.Tests/A.Tests.csproj", "tests/B.Tests/B.Tests.csproj")
$testRunFailed = $false
foreach ($configuration in "Debug", "Release") {
    foreach ($architecture in "x86", "x64") {
        foreach ($testProject in $testProjects) {
            dotnet test --project $testProject -c $configuration --arch $architecture
            if ($LASTEXITCODE -ne 0) {
                $testRunFailed = $true
            }
        }
    }
}
if ($testRunFailed) {
    throw "One or more test runs failed."
}

Argumenty związane z testem są specyficzne dla programu VSTest i dlatego należy je przekształcić w celu dopasowania do nowej platformy. W poniższej tabeli przedstawiono mapowanie między argumentami VSTest a nową platformą:

--collect

--collect to ogólny punkt rozszerzalności w programie VSTest dla dowolnego modułu zbierającego dane. Model rozszerzalności MTP jest inny i nie ma tak scentralizowanego argumentu, który ma być używany przez wszystkie moduły zbierające dane. W przypadku protokołu MTP każdy moduł zbierający dane może dodać własną opcję wiersza polecenia. Na przykład uruchomienie programu Microsoft CodeCoverage za pośrednictwem programu VSTest może być podobne do następujących:

dotnet test --collect "Code Coverage;Format=cobertura"

W przypadku protokołu MTP staje się to następujące:

dotnet test --coverage --coverage-output-format cobertura

--filter

--filter jest filtrem opartym na programie VSTest.

Narzędzia MSTest i NUnit obsługują ten sam format filtru, nawet w przypadku uruchamiania z użyciem protokołu MTP.

xUnit.net nie obsługuje tego samego formatu filtru podczas uruchamiania z MTP. Należy przeprowadzić migrację z filtru opartego na VSTest do nowej obsługi filtru w xunit.v3, co jest realizowane za pomocą następujących opcji wiersza poleceń.

Opcje specyficzne dla xUnit.net:

• --filter-class
• --filter-not-class
• --filter-method
• --filter-not-method
• --filter-namespace
• --filter-not-namespace
• --filter-trait
• --filter-not-trait
• --filter-query

Aby uzyskać więcej informacji, zobacz dokumentację Microsoft.Testing.Platform dotyczącą języka xUnit.net i języka filtrowania zapytań dla xUnit.net.

--logger

To, co w programie VSTest zwykle nazywa się "rejestratorem", jest określane jako "reporter" w MTP. W usłudze MTP rejestrowanie jest jawnie przeznaczone tylko do celów diagnostycznych.

Podobnie jak --collect, --logger jest ogólnym punktem rozszerzalności w programie VSTest dla dowolnego rejestratora (lub, w kontekście protokołu MTP, dowolnego reportera). Każdy reporter MTP ma swobodę dodawania własnej opcji wiersza polecenia, w związku z czym nie ma scentralizowanej opcji wiersza polecenia, takiej jak w VSTest.

Jednym z bardzo często używanych rejestratorów VSTest jest rejestrator TRX. Ten rejestrator jest zwykle wywoływany w następujący sposób:

dotnet test --logger trx

W przypadku protokołu MTP polecenie staje się następujące:

dotnet test --report-trx

GitHub Actions opcje reportera są specyficzne dla pakietu i nie są zamienne:

Aplikacja testowa rozpoznaje opcję tylko wtedy, gdy pakiet, który jest jego właścicielem, jest zainstalowany i zarejestrowany. Jeśli na przykład zmigrujesz --logger GitHubActions i zachowasz pakiet GitHubActionsTestLogger, zastąp polecenie VSTest:

dotnet test --logger GitHubActions

W przypadku zestawu .NET 10 SDK i nowszych wersji użyj:

dotnet test --report-github

W przypadku zestawu SDK platformy .NET 9 i wcześniejszych wersji użyj zamiast tego elementu dotnet test -- --report-github.

--settings

Narzędzia VSTest's --settings są używane do określenia pliku RunSettings dla uruchomienia testów. Element RunSettings nie jest obsługiwany przez rdzeń MTP i został zastąpiony bardziej nowoczesnym testconfig.json plikiem konfiguracji. Jednak narzędzia MSTest i NUnit nadal obsługują stare ustawienia RunSettings podczas uruchamiania protokołu MTP i --settings nadal są obsługiwane.

vstest.console.exe

Jeśli używasz vstest.console.exe bezpośrednio, zalecamy zastąpienie go poleceniem dotnet test .

Eksplorator testów

W przypadku korzystania z eksploratora testów Visual Studio lub Visual Studio Code może być konieczne włączenie obsługi protokołu MTP.

Visual Studio

Visual Studio Eksplorator testów obsługuje protokół MTP począwszy od wersji 17.14. Jeśli używasz starszej wersji, może być konieczne zaktualizowanie programu Visual Studio do najnowszej wersji.

Visual Studio Code

Visual Studio Code z zestawem deweloperskim języka C# obsługuje protokół MTP.

Azure DevOps

W przypadku korzystania z zadań Azure DevOps, może być konieczne zaktualizowanie potoku, aby użyć protokołu MTP, w zależności od konkretnego zadania, którego używasz.

VsTest, zadanie

Jeśli używasz zadania VSTest w usłudze Azure DevOps, możesz zastąpić je zadaniem platformy .NET Core.

Zadanie interfejsu wiersza polecenia platformy .NET Core

• Jeśli przekazano niestandardowe arguments do zadania, postępuj zgodnie z tymi samymi wskazówkami dotyczącymi migracji dotnet test.

• Jeśli używasz DotNetCoreCLI bez zaznaczenia opcji natywnego środowiska MTP dla zestawu SDK .NET 10 i nowszych za pośrednictwem pliku global.json, zadanie arguments musi być ustawione tak, aby prawidłowo wskazywać katalog wyników, który był wcześniej używany, oraz żądany raport TRX. Przykład:

  - task: DotNetCoreCLI@2
    displayName: Run unit tests
    inputs:
      command: 'test'
      arguments: '-- --report-trx --results-directory $(Agent.TempDirectory)'
  

  Aplikacje testowe w tym przykładzie muszą zarejestrować plik Microsoft.Testing.Extensions.TrxReport. Dodaj pakiet bezpośrednio lub użyj konfiguracji lub profilu zestawu SDK testów, który go zawiera.

Różnice behawioralne między narzędziami VSTest i MTP

Uruchamianie testów zerowych

Jeśli zestaw testowy nie uruchomił żadnych testów, program VSTest toleruje to i zakończy się powodzeniem. Jednak MTP kończy się niepowodzeniem z kodem wyjścia 8. Istnieje wiele sposobów obejścia tego:

• Przekaż --ignore-exit-code 8 podczas uruchamiania testów.

• Jeśli chcesz zignorować ten kod zakończenia dla określonego projektu testowego, dodaj następujący kod w pliku projektu:

  <PropertyGroup>
    <TestingPlatformCommandLineArguments>$(TestingPlatformCommandLineArguments) --ignore-exit-code 8</TestingPlatformCommandLineArguments>
  </PropertyGroup>
  

• Użyj zmiennej środowiskowej TESTINGPLATFORM_EXITCODE_IGNORE .

Zachowanie Console.InputEncoding

Jeśli uruchamiasz testy w konsoli, w której strona kodowa została jawnie zmieniona (na przykład w Azure DevOps, strona kodowa jest ustawiona na 65001, która odpowiada UTF8), zachowanie może być inne między programem VSTest i MTP.

• W przypadku protokołu MTP kodowanie jest zawsze zachowywane.
• Jeśli program VSTest nie działa w trybie izolacji (domyślne zachowanie vstest.console), to kodowanie jest zachowywane, podobnie jak W przypadku protokołu MTP.
• W programie VSTest uruchomionym w trybie izolacji (domyślne zachowanie dotnet test) kodowanie nie jest zachowywane w hoście testowym, czyli w procesie, w którym są uruchamiane testy.

Jeśli masz test, który uruchamia kolejny proces podrzędny i przekierowuje jego standardowe dane wyjściowe, możesz napotkać problemy, jeśli wszystkie następujące elementy mają zastosowanie:

• Strona kodowa konsoli jest ustawiona na wartość 65001 (UTF8). Może tak być w przypadku CI, ale z reguły nie lokalnie. Aby uzyskać lokalne zachowanie podobne do tego w systemie CI, uruchom polecenie chcp 65001 przed uruchomieniem testów.
• Proces podrzędny rozpoczyna się od kodowania innego niż UTF8. Może się to również zdarzyć, jeśli twój własny test również ustawia wartość CreateNoWindow = true.

Jest to szczególnie problematyczne, gdy proces podrzędny nie oczekuje, że napotka bajt BOM UTF8 (znak kolejności bajtów), na co może trafić w poprzednim scenariuszu w środowisku .NET Framework.

Ponieważ ta różnica w zachowaniu może być problematyczna w szczególności dla bajtu BOM, obejściem jest ustawienie InputEncoding podczas inicjowania zestawu na UTF8 bez BOM:

Console.InputEncoding = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);

Innym obejściem tego problemu jest brak użycia CreateNoWindow = true w przypadku procesów podrzędnych, które przekierowują standardowe dane wejściowe.