Microsoft.Testing.Platform (MTP) - ustawienia konfiguracji

Protokół MTP obsługuje używanie plików konfiguracji i zmiennych środowiskowych do konfigurowania zachowania platformy testowej. W tym artykule opisano ustawienia konfiguracji, których można użyć do skonfigurowania platformy testowej.

testconfig.json

Platforma testowa używa pliku konfiguracji o nazwie [appname].testconfig.json w celu skonfigurowania zachowania platformy testowej. Plik testconfig.json jest plikiem JSON zawierającym ustawienia konfiguracji platformy testowej.

Plik testconfig.json ma następującą strukturę:

{
    "platformOptions": {
        "resultDirectory": "./TestResults"
    }
}

Platforma automatycznie wykryje i załaduje [appname].testconfig.json plik znajdujący się w katalogu wyjściowym projektu testowego (blisko pliku wykonywalnego).

W przypadku korzystania z Microsoft.Testing.Platform.MSBuildmożna po prostu utworzyć plik testconfig.json, który zostanie automatycznie zmieniony na [appname].testconfig.json i przeniesiony do katalogu wyjściowego projektu testowego.

Począwszy od protokołu MTP 1.5, możesz użyć argumentu --config-file wiersza polecenia, aby określić ścieżkę do testconfig.json. Ten plik ma pierwszeństwo przed [appname].testconfig.json pliku.

Notatka

Plik.testconfig.json [appname] zostanie zastąpiony w kolejnych kompilacjach.

Użyj scentralizowanego pliku testconfig.json

Jeśli chcesz, aby jeden plik testconfig.json był używany wspólnie przez wiele projektów testowych, możesz umieścić go w centralnym miejscu i przekazać za pośrednictwem --config-file. Jeśli program MSBuild jest dostępny (na przykład dotnet test lub dotnet run), możesz użyć TestingPlatformCommandLineArguments właściwości MSBuild, aby automatycznie przekazać argument. Dodanie tego elementu do katalogu głównego repozytorium Directory.Build.props gwarantuje, że wszystkie projekty testowe używają tej samej konfiguracji:

<PropertyGroup>
  <TestingPlatformCommandLineArguments>
    $(TestingPlatformCommandLineArguments) --config-file $(MSBuildThisFileDirectory)testconfig.json
  </TestingPlatformCommandLineArguments>
</PropertyGroup>

Pierwszeństwo konfiguracji

Jeśli to samo ustawienie można określić na wiele sposobów, MTP rozpoznaje je w następującej kolejności (pierwsze zwycięstwo meczu):

  1. Argumenty wiersza polecenia (na przykład --results-directory)
  2. Zmienne środowiskowe
  3. ustawieniatestconfig.json
  4. Wbudowane wartości domyślne

Opcje platformy

Sekcja platformOptions pliku testconfig.json konfiguruje podstawowe zachowanie platformy testowej. W poniższej tabeli wymieniono wszystkie obsługiwane opcje platformy:

Wpis Wartość domyślna Opis
resultDirectory TestResults Katalog, w którym są umieszczane wyniki testu. Może być ścieżką względną (rozpoznaną z bieżącego katalogu roboczego) lub ścieżką bezwzględną. --results-directory Opcja wiersza polecenia ma pierwszeństwo.
exitProcessOnUnhandledException false Po ustawieniu wartości true proces hosta testów kończy działanie natychmiast w przypadku nieobsłużonych wyjątków, zamiast umożliwiać łagodne zamknięcie. Zmienna TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION środowiskowa (wartości 1 lub 0) ma pierwszeństwo.

Notatka

Istnieją dodatkowe wewnętrzne opcje platformy dla zaawansowanych scenariuszy (takie jak limity czasu potoków nazwanych dla kontrolerów hosta testów). Te opcje są przeznaczone do użytku infrastruktury i nie są tutaj omówione.

Przykład:

{
  "platformOptions": {
    "resultDirectory": "../../TestResults",
    "exitProcessOnUnhandledException": false
  }
}

Zmienne środowiskowe w testconfig.json

Notatka

Dostępne w MTP począwszy od wersji 2.3.0.

Sekcja environmentVariables ustawia zmienne środowiskowe dla procesu testowego przed rozpoczęciem. Użyj wartości ciągu dla każdej zmiennej.

{
  "environmentVariables": {
    "DOTNET_ENVIRONMENT": "Development",
    "FEATURE_FLAG": "true"
  }
}

Opcje wiersza poleceń w pliku testconfig.json

Przed wersją MTP 2.3.0 funkcji rozszerzeń, takich jak zrzut awarii, zrzut z zawieszenia, ponowienia, raporty TRX i pokrycie kodu, nie można konfigurować za pośrednictwem testconfig.json. Te funkcje są konfigurowane wyłącznie za pomocą argumentów wiersza polecenia.

Od wersji MTP 2.3.0 program MTP może odczytywać opcje CLI z pliku testconfig.json za pośrednictwem IConfiguration. To wsparcie obejmuje także opcje rozszerzeń, dzięki czemu możesz użyć wpisów JSON do określenia opcji, których nie chcesz przekazywać w wierszu polecenia przy każdym uruchomieniu. Argumenty wiersza polecenia nadal mają pierwszeństwo.

Konfiguracja nie instaluje ani nie rejestruje rozszerzenia. Każda aplikacja testowa musi odwoływać się do pakietu, który zapewnia opcję rozszerzenia, bezpośrednio lub za pośrednictwem konfiguracji lub profilu zestawu SDK testowego. W przeciwnym razie opcja pozostaje nierozpoznana niezależnie od tego, czy umieścisz ją w testconfig.json , czy w wierszu polecenia.

Użyj obiektu commandLineOptions dla aktywnych opcji. Pomiń początkowe -- w każdym kluczu. Użyj true dla opcji bezargumentowej, a false, aby wyłączyć opcję. W przypadku jednego argumentu użyj ciągu lub liczby. W przypadku powtarzających się lub wielu argumentów użyj tablicy:

{ "commandLineOptions": {
  "report-trx": true,
  "report-trx-filename": "results.trx",
  "filter-uid": ["test-1", "test-2"]
} }

MTP traktuje łańcuch lub skalar liczbowy jako pierwszy argument opcji przyjmującej argument. Aby przekazać argument typu Boolean, użyj tablicy, na przykład [true] lub [false]. Tablica odróżnia argument od boolowskiej wartości określającej obecność.

Protokół MTP weryfikuje skonfigurowane wpisy, takie jak wpisy wiersza polecenia. Nieznane opcje, nieprawidłowe wartości i wartości o niewłaściwej liczbie argumentów nie przechodzą walidacji. Jawna opcja wiersza polecenia zastępuje odpowiedni commandLineOptions wpis.

Opcje tylko rozruchowe są stosowane przed wczytaniem konfiguracji przez MTP. Nie umieszczaj config-file, , diagnostic, diagnostic-output-directory, diagnostic-file-prefix, diagnostic-verbosity, diagnostic-synchronous-write, ani enable-dynamic-extensions w .commandLineOptions

Domyślne wartości pasywnej opcji wiersza polecenia

Ważna

commandLineOptionDefaults jest dostępny w wersji zapoznawczej MTP 2.4.

Służy commandLineOptionDefaults do podawania argumentu tylko wtedy, gdy włączona funkcja żąda tej opcji i nie istnieje żadna wartość o wyższym priorytcie. Pasywna wartość domyślna nie włącza opcji, rejestrowania rozszerzenia ani aktywowania funkcji. Pomiń początkowe -- z każdego klucza.

{ "commandLineOptionDefaults": {
  "report-trx-filename": "{asm}.trx",
  "show-test-results": ["failed", "skipped"]
} }

MTP ustala wartość opcji na podstawie pierwszego dopasowania w następującej kolejności priorytetów:

  • Wartość podana jawnie w wierszu polecenia.
  • commandLineOptions Aktywny wpis.
  • commandLineOptionDefaults wpis w testconfig.json.
  • Wartość domyślna podana przez program MSBuild.

Aby użyć wartości domyślnej dostarczanej przez MSBuild, dodaj element TestingPlatformCommandLineOptionDefault. Wartość Include musi pominąć wiodące łączniki:

<TestingPlatformCommandLineOptionDefault Include="report-trx-filename"
                                         Value="{asm}.trx" />

Aby uzyskać pełną dokumentację opcji wiersza polecenia, zobacz Dokumentację opcji interfejsu wiersza polecenia MTP.

Ustawienia specyficzne dla platformy testowej

Struktury testowe mogą definiować własne sekcje konfiguracji w pliku testconfig.json . Zapoznaj się z dokumentacją platformy testowej:

Przykład testconfig.json

W poniższym przykładzie przedstawiono plik testconfig.json , który konfiguruje opcje platformy i ustawienia MSTest:

{
  "platformOptions": {
    "resultDirectory": "./TestResults"
  },
  "mstest": {
    "parallelism": {
      "enabled": true,
      "workers": 4,
      "scope": "method"
    },
    "timeout": {
      "test": 30000
    },
    "execution": {
      "considerFixturesAsSpecialTests": true
    }
  }
}

Migrowanie z pliku .runsettings do testconfig.json

W przypadku migracji z pliku .runsettings poniższa tabela mapuje typowe ustawienia na ich testconfig.json odpowiedniki lub alternatywy:

Ustawienie .runsettings odpowiednik testconfig.json Notatki
RunConfiguration/ResultsDirectory platformOptions.resultDirectory
RunConfiguration/MaxCpuCount Brak odpowiednika Równoległość na poziomie procesu jest sterowana za pomocą opcji dotnet test --max-parallel-test-modules lub opcji MSBuild /m.
MSTest/* mstest.* Zobacz Konfigurowanie narzędzia MSTest — testconfig.json.
xUnit/* xUnit.* Zobacz xUnit.net testconfig.json.
LoggerRunSettings/Loggers Opcje CLI Użyj opcji z zainstalowanego rozszerzenia raportu. Na przykład --report-trx wymaga Microsoft.Testing.Extensions.TrxReport. Od wersji MTP 2.3.0 program MTP może odczytywać opcje CLI z testconfig.json. Zobacz Raporty testowe.
DataCollectionRunSettings (obwinianie) Opcje CLI Użyj --crashdump z Microsoft.Testing.Extensions.CrashDump lub --hangdump z Microsoft.Testing.Extensions.HangDump. Od wersji MTP 2.3.0 program MTP może odczytywać opcje CLI z testconfig.json. Zobacz Awaria i zawieszanie zrzutów.
DataCollectionRunSettings (pokrycie) Opcje CLI Użyj --coverage z Microsoft.Testing.Extensions.CodeCoverage. Od wersji MTP 2.3.0 program MTP może odczytywać opcje CLI z testconfig.json. Zobacz Pokrycie kodu.
TestRunParameters --test-parameter Interfejs linii komend (CLI) Użyj polecenia --test-parameter key=value w wierszu polecenia.

Konfiguracja programu MSBuild

Ważna

TestingPlatformEnvironmentVariable jest dostępny w wersji zapoznawczej MTP 2.4.

Aby ustawić zmienną środowiskową w procesie testowym uruchamianym przez InvokeTestingPlatform, dodaj element TestingPlatformEnvironmentVariable:

<TestingPlatformEnvironmentVariable Include="MY_OPTIONS"
                                    Value="first;second" />

Metadane Value zachowują średniki zamiast dzielić je na elementy MSBuild. Zadeklarowane wartości są nakładane na środowisko dziedziczone przez proces MSBuild. Bez tych elementów uruchamiany proces dziedziczy środowisko w niezmienionej postaci.

Zmienne środowiskowe

Zmienne środowiskowe mogą służyć do dostarczania niektórych informacji o konfiguracji środowiska uruchomieniowego.

Notatka

Zmienne środowiskowe mają pierwszeństwo przed ustawieniami konfiguracji w pliku testconfig.json.

zmienna środowiskowa TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION

Gdy jest ustawiona wartość 1, proces hosta testowego jest natychmiast zamykany w przypadku nieobsługiwanych wyjątków. Po ustawieniu na 0 platforma umożliwia łagodne zamykanie. To ustawienie ma pierwszeństwo przed konfiguracją platformOptions:exitProcessOnUnhandledException .

zmienna środowiskowa TESTINGPLATFORM_DEFAULT_HANG_TIMEOUT

Nadpisuje domyślny limit czasu (300 sekund) używany dla połączeń za pomocą nazwanych potoków między kontrolerem hosta testowego a hostem testowym. Wartość musi być ciągiem znaków zgodnym z TimeSpan.

zmienna środowiskowa TESTINGPLATFORM_UI_LANGUAGE

Począwszy od protokołu MTP 1.5, ta zmienna środowiskowa ustawia język platformy do wyświetlania komunikatów i dzienników przy użyciu wartości ustawień regionalnych, takich jak en-us. Ten język ma pierwszeństwo przed językami programu Visual Studio i zestawu .NET SDK. Obsługiwane wartości są takie same jak w przypadku programu Visual Studio. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą zmiany języka instalatora w dokumentacji instalacji programu Visual Studio.

zmienna środowiskowa TESTINGPLATFORM_DIAGNOSTIC

Jeśli ustawiono wartość 1, włącza rejestrowanie diagnostyczne.

zmienna środowiskowa TESTINGPLATFORM_DIAGNOSTIC_VERBOSITY

Określa poziom szczegółowości przy włączonej diagnostyce. Dostępne wartości to Trace, Debug, Information, Warning, Errorlub Critical.

zmienna środowiskowa TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_DIRECTORY

Katalog wyjściowy rejestrowania diagnostycznego. Jeśli nie zostanie określony, plik zostanie wygenerowany w domyślnym katalogu TestResults .

zmienna środowiskowa TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX

Prefiks nazwy pliku dziennika. Domyślnie MTP używa <asm>_<tfm>_<arch> i dołącza znacznik czasu. Wynikowa nazwa pliku to <asm>_<tfm>_<arch>_<timestamp>.diag. Zmienna jest zgodna z opcją --diagnostic-file-prefix wiersza polecenia.

Notatka

Ta nazwa zmiennej środowiskowej jest dostępna w MTP, począwszy od wersji 2.3.0. Starsza TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_FILEPREFIX zmienna środowiskowa jest nadal honorowana w celu zachowania zgodności z poprzednimi wersjami, ale jest przestarzała i może zostać usunięta w przyszłej wersji głównej. Gdy obie zmienne są ustawione, pierwszeństwo ma TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX.

zmienna środowiskowa TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE

Wymusza synchroniczne zapisywanie logów przez wbudowany rejestrator plików. Przydatne w scenariuszach, w których nie chcesz utracić żadnych wpisów dziennika (jeśli proces ulegnie awarii). Spowoduje to spowolnienie wykonywania testu. Odpowiada opcji wiersza polecenia --diagnostic-synchronous-write.

Notatka

Ta nazwa zmiennej środowiskowej jest dostępna w MTP, począwszy od wersji 2.3.0. Starsza TESTINGPLATFORM_DIAGNOSTIC_FILELOGGER_SYNCHRONOUSWRITE zmienna środowiskowa jest nadal honorowana w celu zachowania zgodności z poprzednimi wersjami, ale jest przestarzała i może zostać usunięta w przyszłej wersji głównej. Gdy obie zmienne są ustawione, pierwszeństwo ma TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE.

zmienna środowiskowa TESTINGPLATFORM_EXITCODE_IGNORE

Lista kodów zakończenia rozdzielonych średnikami, które mają zostać zignorowane. Gdy kod zakończenia jest ignorowany, proces zwraca 0 zamiast tego. Na przykład TESTINGPLATFORM_EXITCODE_IGNORE=2;8 ignoruje niepowodzenia testów i scenariusze bez testów.

zmienna środowiskowa TESTINGPLATFORM_NOBANNER

Po ustawieniu na 1 lub true powoduje pominięcie banera startowego, komunikatu o prawach autorskich i banera telemetrii. Odpowiednik opcji --no-banner wiersza polecenia. Zmienna DOTNET_NOLOGO środowiskowa ma taki sam efekt.

zmienna środowiskowa NO_COLOR

Po ustawieniu na dowolną niepustą wartość wyłącza wszystkie kolorowe dane wyjściowe ANSI. MTP przestrzega NO_COLOR konwencji.

Notatka

Dostępne w MTP począwszy od wersji 2.3.0.

zmienna środowiskowa DOTNET_NOLOGO

Po ustawieniu na 1 lub true powoduje pominięcie banera startowego, komunikatu o prawach autorskich i banera telemetrii. Jest to standardowa zmienna środowiskowa interfejsu wiersza polecenia .NET i jest honorowana przez MTP. Zobacz również TESTINGPLATFORM_NOBANNER.

zmienna środowiskowa TESTINGPLATFORM_PIPE_DIRECTORY

Od wersji MTP 2.4.0 ta zmienna nadpisuje katalog, w którym MTP tworzy pliki gniazd domeny Unix do komunikacji za pomocą nazwanych potoków. Użyj go, gdy piaskownica lub kontener nie zezwala na tworzenie gniazd w domyślnym katalogu tymczasowym. MTP tworzy i sprawdza katalog, a następnie zgłasza błąd, gdy katalog nie jest zapisywalny lub wynikowa ścieżka do gniazda jest za długa.

Zmienna nie ma wpływu w systemie Windows, w którym nazwane potoki nie korzystają ze ścieżek systemu plików. Nie przenosi również potoku utworzonego przez inny proces, na przykład zestaw SDK .NET.

Prototyp anulowania terminu ostatecznego

Warning

EKSPERYMENTALNE/PROTOTYPOWE: Anulowanie terminu ostatecznego jest prototypem w wersji zapoznawczej MTP 2.4. Jego zmienne i zachowanie można zmienić lub usunąć.

Ustaw TESTINGPLATFORM_DEADLINE na pełny moment natychmiastowego twardego anulowania dostarczony przez komponent wyznaczający termin. Użyj wartości ISO 8601 UTC. Nie odejmuj marginesów MTP od wartości.

MTP żąda łagodnego zatrzymania przed upływem terminu. TESTINGPLATFORM_DEADLINE_STOP_MARGIN określa, jak wcześnie i domyślnie jest to 60 sekund. Platforma testowa, która nie obsługuje bezpiecznego zatrzymania, ignoruje to żądanie.

Awaryjnie TESTINGPLATFORM_DEADLINE_DUMP_MARGIN uruchamia aktywne rozszerzenie HangDump przed upływem terminu. Margines domyślnie wynosi 30 sekund. HangDump przechwytuje drzewo procesów, a następnie zabija hosta testowego. Bez terminu MTP nie uruchamia czasomierza terminu ostatecznego.

Podmiot wyznaczający termin nadal odpowiada za bezwzględne anulowanie we wskazanym momencie.

zmienna środowiskowa TESTINGPLATFORM_WAIT_ATTACH_DEBUGGER

Gdy jest ustawiona wartość 1, proces testowania wstrzymuje się podczas uruchamiania i czeka na dołączenie debugera przed kontynuowaniem. Odpowiednik opcji --debug wiersza polecenia. Nieobsługiwane na platformach przeglądarki.

Notatka

Ta zmienna środowiskowa jest dostępna w MTP, począwszy od wersji 1.6.0.

zmienna środowiskowa TESTINGPLATFORM_LAUNCH_ATTACH_DEBUGGER

Po ustawieniu opcji na 1 proces testowy wywołuje przy uruchomieniu Debugger.Launch(), co powoduje, że system uruchamia debuger just-in-time i dołącza go do procesu. Użyj tej zmiennej do debugowania problemów podczas uruchamiania (na przykład uzgadniania połączenia w trybie serwera), które występują, zanim będzie można ręcznie się podłączyć. W przypadku platform innych niż Windows zachowanie zależy od skonfigurowanego debugera JIT.

Notatka

Ta zmienna środowiskowa jest dostępna w MTP, począwszy od wersji 1.6.0.

Notatka

Zmienne środowiskowe związane z diagnostyką mają pierwszeństwo przed odpowiadającymi im --diagnostic-* argumentami wiersza polecenia.

Zobacz także

  • Last updated on