Microsoft.Testing.Platform (MTP) pengaturan konfigurasi

MTP mendukung penggunaan file konfigurasi dan variabel lingkungan untuk mengonfigurasi perilaku platform pengujian. Artikel ini menjelaskan pengaturan konfigurasi yang dapat Anda gunakan untuk mengonfigurasi platform pengujian.

testconfig.json

Platform pengujian menggunakan file konfigurasi bernama [appname].testconfig.json untuk mengonfigurasi perilaku platform pengujian. File testconfig.json adalah file JSON yang berisi pengaturan konfigurasi untuk platform pengujian.

File testconfig.json memiliki struktur berikut:

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

Platform akan secara otomatis mendeteksi dan memuat file.testconfig.json [appname] yang terletak di direktori output proyek pengujian (dekat dengan yang dapat dieksekusi).

Saat menggunakan Microsoft.Testing.Platform.MSBuild, Anda cukup membuat file testconfig.json yang akan secara otomatis diganti namanya menjadi [nama aplikasi].testconfig.json dan dipindahkan ke direktori output proyek pengujian.

Dimulai dengan MTP 1.5, Anda dapat menggunakan argumen --config-file baris perintah untuk menentukan jalur ke testconfig.json. File ini lebih diutamakan daripada file.testconfig.json [appname].

Nota

File.testconfig.json [appname] akan ditimpa pada build berikutnya.

Menggunakan testconfig.json terpusat

Jika Anda ingin satu testconfig.json dibagikan di beberapa proyek pengujian, Anda dapat menempatkannya di lokasi pusat dan meneruskannya melalui --config-file. Saat MSBuild tersedia (misalnya, dotnet test atau dotnet run), Anda dapat menggunakan TestingPlatformCommandLineArguments properti MSBuild untuk meneruskan argumen secara otomatis. Menambahkan ini ke Directory.Build.props di akar repositori memastikan semua proyek pengujian menggunakan konfigurasi yang sama:

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

Urutan prioritas konfigurasi

Ketika pengaturan yang sama dapat ditentukan dalam beberapa cara, MTP menyelesaikannya dalam urutan berikut (kemenangan pertandingan pertama):

  1. Argumen baris perintah (misalnya, --results-directory)
  2. Variabel lingkungan
  3. testconfig.json setelan
  4. Setelan bawaan

Pilihan platform

Bagian platformOptions file testconfig.json mengonfigurasi perilaku inti platform pengujian. Tabel berikut ini mencantumkan semua opsi platform yang didukung:

Entri Default Description
resultDirectory TestResults Direktori tempat hasil pengujian ditempatkan. Dapat berupa jalur relatif (diselesaikan dari direktori kerja saat ini) atau jalur absolut. Opsi --results-directory baris perintah lebih diutamakan.
exitProcessOnUnhandledException false Ketika diatur ke true, proses host uji langsung keluar saat terjadi pengecualian yang tidak tertangani, alih-alih memungkinkan proses dimatikan secara normal. Variabel TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION lingkungan (nilai 1 atau 0) lebih diutamakan.

Nota

Opsi platform internal tambahan ada untuk skenario lanjutan (seperti batas waktu pipa bernama untuk pengontrol host pengujian). Opsi ini ditujukan untuk penggunaan infrastruktur dan tidak tercakup di sini.

Contoh:

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

Variabel lingkungan dalam testconfig.json

Nota

Tersedia di MTP yang dimulai dengan versi 2.3.0.

Bagian ini environmentVariables mengatur variabel lingkungan untuk proses pengujian sebelum dimulai. Gunakan nilai string untuk setiap variabel.

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

Opsi CLI di testconfig.json

Sebelum MTP 2.3.0, fitur ekstensi seperti crash dump, hang dump, coba lagi, laporan TRX, dan cakupan kode tidak dapat dikonfigurasi melalui testconfig.json. Fitur-fitur ini dikonfigurasi secara eksklusif melalui argumen baris perintah.

Dimulai dengan MTP 2.3.0, MTP dapat membaca opsi CLI dari testconfig.json melalui IConfiguration. Dukungan ini mencakup opsi ekstensi, sehingga Anda dapat menggunakan entri JSON untuk opsi yang tidak ingin Anda teruskan pada baris perintah setiap eksekusi. Argumen baris perintah masih diutamakan.

Konfigurasi tidak menginstal atau mendaftarkan ekstensi. Setiap aplikasi pengujian harus mereferensikan paket yang menyediakan opsi ekstensi, baik secara langsung atau melalui konfigurasi atau profil SDK pengujian. Jika tidak, opsi tetap tidak dikenali apakah Anda memasukkannya ke testconfig.json atau pada baris perintah.

commandLineOptions Gunakan objek untuk opsi aktif. Hilangkan yang terdepan -- dari setiap kunci. Gunakan true untuk opsi nol argumen, dan gunakan false untuk menonaktifkan opsi. Untuk satu argumen, gunakan string atau angka. Untuk argumen berulang atau beberapa, gunakan array:

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

MTP memperlakukan string atau skalar angka sebagai argumen pertama dari opsi pembawa argumen. Untuk meneruskan argumen Boolean, gunakan array seperti [true] atau [false]. Array membedakan argumen dari nilai kehadiran Boolean.

MTP memvalidasi entri yang dikonfigurasi seperti entri baris perintah. Opsi yang tidak dikenal, nilai yang tidak valid, dan nilai dengan aritas yang salah tidak lolos validasi. Opsi command-line yang eksplisit mengesampingkan entri commandLineOptions yang sesuai.

Opsi khusus bootstrap berjalan sebelum MTP memuat konfigurasi. Jangan letakkan config-file, , diagnosticdiagnostic-output-directory, diagnostic-file-prefix, diagnostic-verbosity, diagnostic-synchronous-write, atau enable-dynamic-extensions di commandLineOptions.

Default opsi baris perintah pasif

Important

commandLineOptionDefaults tersedia dalam pratinjau MTP 2.4.

Gunakan commandLineOptionDefaults untuk menyediakan argumen hanya ketika fitur yang diaktifkan meminta opsi tersebut dan tidak ada nilai prioritas yang lebih tinggi. Default pasif tidak mengaktifkan opsi, mendaftarkan ekstensi, atau mengaktifkan fitur. Hilangkan yang terdepan -- dari setiap kunci.

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

MTP menyelesaikan nilai opsi dengan menggunakan kecocokan pertama dalam urutan prioritas ini:

  • Nilai baris perintah eksplisit.
  • Sebuah entri aktif commandLineOptions.
  • Entri commandLineOptionDefaults di testconfig.json.
  • Nilai bawaan yang disediakan oleh MSBuild.

Untuk default yang disediakan MSBuild, tambahkan TestingPlatformCommandLineOptionDefault item. Nilai Include harus menghilangkan tanda hubung di depan:

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

Untuk referensi lengkap opsi baris perintah, lihat Referensi opsi MTP CLI.

Menguji pengaturan khusus kerangka kerja

Kerangka kerja pengujian dapat menentukan bagian konfigurasi mereka sendiri dalam file testconfig.json . Lihat dokumentasi untuk kerangka kerja pengujian Anda:

Contoh testconfig.json

Contoh berikut menunjukkan file testconfig.json yang mengonfigurasi opsi platform dan pengaturan MSTest:

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

Migrasi dari .runsettings ke testconfig.json

Jika Anda bermigrasi dari file .runsettings , tabel berikut memetakan pengaturan umum ke testconfig.json setara atau alternatifnya:

Pengaturan .runsettings testconfig.json yang setara dengan Catatan
RunConfiguration/ResultsDirectory platformOptions.resultDirectory
RunConfiguration/MaxCpuCount Tidak ada yang setara Paralelisme tingkat proses dikendalikan oleh dotnet test --max-parallel-test-modules atau opsi MSBuild /m .
MSTest/* mstest.* Lihat Mengonfigurasi MSTest — testconfig.json.
xUnit/* xUnit.* Lihat xUnit.net testconfig.json.
LoggerRunSettings/Loggers Opsi CLI Gunakan opsi dari ekstensi laporan yang diinstal. Misalnya, --report-trx memerlukan Microsoft.Testing.Extensions.TrxReport. Dimulai dengan MTP 2.3.0, MTP dapat membaca opsi CLI dari testconfig.json. Lihat Laporan pengujian.
DataCollectionRunSettings (menyalahkan) Opsi CLI Gunakan --crashdump dari Microsoft.Testing.Extensions.CrashDump atau --hangdump dari Microsoft.Testing.Extensions.HangDump. Dimulai dengan MTP 2.3.0, MTP dapat membaca opsi CLI dari testconfig.json. Lihat Crash dan hang dump.
DataCollectionRunSettings (cakupan) Opsi CLI Gunakan --coverage dari Microsoft.Testing.Extensions.CodeCoverage. Dimulai dengan MTP 2.3.0, MTP dapat membaca opsi CLI dari testconfig.json. Lihat Cakupan kode.
TestRunParameters --test-parameter CLI Gunakan --test-parameter key=value pada baris perintah.

Konfigurasi MSBuild

Important

TestingPlatformEnvironmentVariable tersedia dalam pratinjau MTP 2.4.

Untuk mengatur variabel lingkungan pada proses pengujian yang InvokeTestingPlatform diluncurkan, tambahkan TestingPlatformEnvironmentVariable item:

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

Metadata Value mempertahankan titik koma alih-alih membaginya menjadi item MSBuild. Nilai yang dinyatakan melapisi lingkungan yang diwarisi proses MSBuild. Tanpa item ini, proses yang diluncurkan mewarisi lingkungan yang tidak berubah.

Variabel lingkungan

Variabel lingkungan dapat digunakan untuk menyediakan beberapa informasi konfigurasi runtime.

Nota

Variabel lingkungan lebih diutamakan daripada pengaturan konfigurasi dalam file testconfig.json.

variabel lingkungan TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION

Ketika diatur ke 1, proses host uji akan langsung keluar saat terjadi pengecualian yang tidak tertangani. Ketika diatur ke 0, platform memungkinkan penghentian secara elegan. Pengaturan ini lebih diutamakan daripada platformOptions:exitProcessOnUnhandledException konfigurasi.

variabel lingkungan TESTINGPLATFORM_DEFAULT_HANG_TIMEOUT

Mengganti waktu tunggu default (300 detik) yang digunakan untuk koneksi named pipe antara pengontrol host pengujian dan host pengujian. Nilai harus berupa TimeSpanstring yang kompatibel.

variabel lingkungan TESTINGPLATFORM_UI_LANGUAGE

Dimulai dengan MTP 1.5, variabel lingkungan ini mengatur bahasa platform untuk menampilkan pesan dan log menggunakan nilai lokal seperti en-us. Bahasa ini lebih diutamakan daripada bahasa Visual Studio dan .NET SDK. Nilai yang didukung sama seperti untuk Visual Studio. Untuk informasi selengkapnya, lihat bagian tentang mengubah bahasa penginstal dalam dokumentasi penginstalan Visual Studio.

variabel lingkungan TESTINGPLATFORM_DIAGNOSTIC

Jika diatur ke 1, mengaktifkan pembuatan log diagnostik.

variabel lingkungan TESTINGPLATFORM_DIAGNOSTIC_VERBOSITY

Menentukan tingkat verbositas saat diagnostik diaktifkan. Nilai yang tersedia adalah Trace, Debug, Information, Warning, Error, atau Critical.

variabel lingkungan TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_DIRECTORY

Direktori keluaran untuk pencatatan log diagnostik. Jika tidak ditentukan, file dihasilkan di direktori TestResults default.

variabel lingkungan TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX

Awalan untuk nama file log. Secara default, MTP menggunakan <asm>_<tfm>_<arch> dan menambahkan tanda waktu. Nama file yang dihasilkan adalah <asm>_<tfm>_<arch>_<timestamp>.diag. Variabel cocok dengan --diagnostic-file-prefix opsi baris perintah.

Nota

Nama variabel lingkungan ini tersedia di MTP yang dimulai dengan versi 2.3.0. Variabel lingkungan warisan TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_FILEPREFIX masih didukung demi kompatibilitas ke belakang, tetapi telah didepresiasi dan mungkin dihapus pada versi utama mendatang. Ketika kedua variabel diatur, TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX diprioritaskan.

variabel lingkungan TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE

Memaksa pencatat file bawaan untuk menulis log secara sinkron. Berguna untuk skenario di mana Anda tidak ingin kehilangan entri log apa pun (jika proses crash). Ini memperlambat eksekusi pengujian. Sesuai dengan opsi baris perintah --diagnostic-synchronous-write.

Nota

Nama variabel lingkungan ini tersedia di MTP yang dimulai dengan versi 2.3.0. Variabel lingkungan warisan TESTINGPLATFORM_DIAGNOSTIC_FILELOGGER_SYNCHRONOUSWRITE masih didukung demi kompatibilitas ke belakang, tetapi telah didepresiasi dan mungkin dihapus pada versi utama mendatang. Ketika kedua variabel diatur, TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE diprioritaskan.

variabel lingkungan TESTINGPLATFORM_EXITCODE_IGNORE

Daftar kode keluar yang diabaikan, dipisahkan dengan titik koma. Ketika kode keluar diabaikan, proses akan kembali 0 sebagai gantinya. Misalnya, TESTINGPLATFORM_EXITCODE_IGNORE=2;8 mengabaikan kegagalan pengujian dan skenario tanpa pengujian yang dijalankan.

variabel lingkungan TESTINGPLATFORM_NOBANNER

Saat diatur ke 1 atau true, opsi ini menyembunyikan banner saat startup, pesan hak cipta, dan banner telemetri. Setara dengan --no-banner opsi baris perintah. Variabel DOTNET_NOLOGO lingkungan memiliki efek yang sama.

variabel lingkungan NO_COLOR

Jika diatur ke nilai apa pun yang tidak kosong, semua keluaran warna ANSI akan dinonaktifkan. MTP menghormati NO_COLOR konvensi.

Nota

Tersedia di MTP yang dimulai dengan versi 2.3.0.

variabel lingkungan DOTNET_NOLOGO

Saat diatur ke 1 atau true, opsi ini menyembunyikan banner saat startup, pesan hak cipta, dan banner telemetri. Ini adalah variabel lingkungan CLI .NET standar dan dihormati oleh MTP. Lihat juga TESTINGPLATFORM_NOBANNER.

variabel lingkungan TESTINGPLATFORM_PIPE_DIRECTORY

Dimulai dengan MTP 2.4.0, variabel ini mengambil alih direktori tempat MTP membuat file soket domain Unix untuk komunikasi pipa bernama. Gunakan saat kotak pasir atau kontainer tidak mengizinkan pembuatan soket di direktori sementara default. MTP membuat dan memeriksa direktori, dan gagal dengan kesalahan ketika direktori tidak dapat ditulis atau jalur soket yang dihasilkan terlalu panjang.

Variabel tersebut tidak berpengaruh di Windows, tempat named pipe tidak menggunakan jalur sistem berkas. Ini juga tidak memindahkan pipa yang dibuat oleh proses lain, seperti .NET SDK.

Prototipe pembatalan tenggat waktu

Warning

EKSPERIMENTAL/PROTOTIPE: Pembatalan tenggat waktu adalah prototipe dalam pratinjau MTP 2.4. Variabel dan perilakunya dapat berubah atau dihapus.

Atur TESTINGPLATFORM_DEADLINE ke instan hard-cancel lengkap yang disediakan oleh produsen tenggat waktu. Gunakan nilai ISO 8601 UTC. Jangan kurangi margin MTP dari nilai.

MTP meminta penghentian secara elegan sebelum batas waktu. TESTINGPLATFORM_DEADLINE_STOP_MARGIN mengatur seberapa dini dan defaultnya adalah 60 detik. Kerangka kerja pengujian yang tidak mendukung penghentian secara aman mengabaikan permintaan ini.

Sebagai cadangan, TESTINGPLATFORM_DEADLINE_DUMP_MARGIN memulai ekstensi HangDump yang aktif sebelum batas waktu. Margin secara default diatur ke 30 detik. HangDump menangkap pohon proses dan kemudian membunuh host pengujian. Tanpa tenggat waktu, MTP tidak memulai penghitung waktu tenggat.

Penghasil tenggat waktu tetap bertanggung jawab untuk melakukan pembatalan paksa pada waktu yang ditentukan.

variabel lingkungan TESTINGPLATFORM_WAIT_ATTACH_DEBUGGER

Ketika diatur ke 1, proses pengujian berhenti sejenak saat startup dan menunggu debugger dilampirkan sebelum melanjutkan. Setara dengan --debug opsi baris perintah. Tidak didukung pada platform browser.

Nota

Variabel lingkungan ini tersedia di MTP yang dimulai dengan versi 1.6.0.

variabel lingkungan TESTINGPLATFORM_LAUNCH_ATTACH_DEBUGGER

Ketika diatur ke 1, proses pengujian memanggil Debugger.Launch() saat mulai dijalankan, yang menyebabkan sistem meluncurkan debugger just-in-time dan melampirkannya ke proses tersebut. Gunakan variabel ini untuk mendebug masalah saat startup (misalnya, handshake mode server) yang terjadi sebelum Anda dapat melakukan attach secara manual. Pada platform non-Windows, perilaku tergantung pada debugger JIT yang dikonfigurasi.

Nota

Variabel lingkungan ini tersedia di MTP yang dimulai dengan versi 1.6.0.

Nota

Variabel lingkungan terkait diagnostik lebih diutamakan daripada argumen baris perintah yang --diagnostic-* sesuai.

Baca juga

  • Last updated on