Поделиться через

Служебная программа для проверки объема протестированного кода dotnet-coverage

  • Статья

Эта статья относится к: ✔️ пакету SDK для .NET Core 3.1 и более поздних версий

Краткие сведения

dotnet-coverage [-h, --help] [--version] <command>

Description

Программа dotnet-coverage —

  • Включает кроссплатформенную коллекцию данных покрытия кода выполняющегося процесса.
  • обеспечивает кросс-платформенное объединение отчетов об объеме протестированного кода.

Параметры

  • -h|--help

    Отображение справки в командной строке.

  • --version

    Отображение версии служебной программы dotnet-coverage.

Установка

Чтобы установить последнюю версию пакета NuGet dotnet-coverage, используйте команду dotnet tool install.

dotnet tool install --global dotnet-coverage

Команды

Команда
dotnet-coverage merge
dotnet-coverage collect
подключение dotnet-coverage
моментальный снимок dotnet-coverage
dotnet-coverage shutdown
инструмент dotnet-coverage

dotnet-coverage merge

Команда merge позволяет объединять несколько отчетов об объеме протестированного кода. Эта команда доступна на всех платформах. Команда поддерживает следующие форматы отчетов о покрытии кода:

  • coverage
  • cobertura
  • xml

Краткие сведения

dotnet-coverage merge
    [--remove-input-files]
    [-o|--output <output>] [-f|--output-format <output-format>]
    [-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
    <files>

Аргументы

  • <files>

    Входящие отчеты об объеме протестированного кода.

Параметры

  • --remove-input-files

    Удаление всех объединенных отчетов об объеме протестированного кода.

  • -r, --recursive

    Пакет SDK для .NET 7 и более ранние версии ищут только отчеты о охвате в подкаталогах.

  • -o|--output <output>

    Задает выходной файла отчета об объеме протестированного кода.

  • -f|--output-format <output-format>

    Формат выходных файлов. Поддерживаемые значения: coverage, xml и cobertura. Значение по умолчанию — coverage (двоичный формат, который можно открыть в Visual Studio).

  • -l|--log-file <log-file>

    Установка пути к файлу журнала. Когда вы указываете каталог (с разделителем пути в конце), создается новый файл журнала для каждого процесса в изучаемой области.

  • -ll|--log-level <log-level>

    Задает уровень ведения журнала. Поддерживаемые значения: Error, Info и Verbose.

dotnet-coverage collect

Команда collect позволяет собирать данные об объеме протестированного кода для любого процесса .NET и его подпроцессов. Например, можно получить данные об объеме протестированного кода для консольного приложения или приложения Blazor. Эта команда поддерживает динамическую и статическую инструментирование. Статическое инструментирование доступно на всех платформах. Вы можете указать файлы, которые будут статически инструментированы с помощью include-files параметра. Динамическое инструментирование доступно в Windows (x86, x64 и Arm64), Linux (x64) и macOS (x64). Команда поддерживает только модули .NET. Нативные модули не поддерживаются.

Краткие сведения

Команда collect может выполняться в двух режимах.

Режим команд

Команда collect собирает покрытие кода для заданного процесса, выполняемого аргументом command .

dotnet-coverage collect
    [-s|--settings <settings>] [-id|--session-id <session-id>]
    [-if|--include-files <include-files>] [-o|--output <output>]
    [-f|--output-format <output-format>] [-l|--log-file <log-file>]
    [-ll|--log-level <log-level>] [-?|-h|--help]
    <command> <args>

Режим сервера

Команда collect размещает сервер для сбора покрытия кода. Клиенты могут подключаться к серверу с помощью connect команды.

dotnet-coverage collect
    [-s|--settings <settings>] [-id|--session-id <session-id>]
    [-sv|--server-mode] [-b|--background] [-t|--timeout]
    [-if|--include-files <include-files>] [-o|--output <output>]
    [-f|--output-format <output-format>] [-l|--log-file <log-file>]
    [-ll|--log-level <log-level>] [-?|-h|--help]

Аргументы

  • <command>

    Команда, для которой должны быть собраны данные об объеме протестированного кода.

  • <args>

    Аргументы командной строки для команды.

Параметры

  • -s|--settings <settings>

    Задает путь к параметрам покрытия кода XML.

  • -id|--session-id <session-id>

    Задает идентификатор сеанса для объема протестированного кода. Если этот параметр не указан, средство создаст случайный идентификатор GUID.

  • -sv|--server-mode

    Запускает сборщик в режиме сервера. Клиенты могут подключаться к серверу с connect помощью команды.

  • -b|--background

    Запускает сервер сбора покрытия кода в новом фоновом процессе. Клиенты могут подключаться к серверу с connect помощью команды.

  • -t|--timeout

    Время ожидания (в миллисекундах) для взаимодействия между клиентами и сервером.

  • -if|--include-files <include-files>

    Указывает список файлов для статического инструментирования.

  • -o|--output <output>

    Задает выходной файла отчета об объеме протестированного кода.

  • -f|--output-format <output-format>

    Формат выходных файлов. Поддерживаемые значения: coverage, xml и cobertura. Значение по умолчанию — coverage (двоичный формат, который можно открыть в Visual Studio).

  • -l|--log-file <log-file>

    Установка пути к файлу журнала. Когда вы указываете каталог (с разделителем пути в конце), создается новый файл журнала для каждого процесса в изучаемой области.

  • -ll|--log-level <log-level>

    Задает уровень ведения журнала. Поддерживаемые значения: Error, Info и Verbose.

подключение dotnet-coverage

Эта connect команда используется для подключения к существующему серверу и собирает данные покрытия кода для любого процесса .NET и его подпроцессов. Например, можно получить данные об объеме протестированного кода для консольного приложения или приложения Blazor. Команда поддерживает только модули .NET. Нативные модули не поддерживаются.

Примечание.

Команда будет использовать динамическое инструментирование для всех подпроцессов, доступных в Windows (x86, x64 и Arm64), Linux (x64) и macOS (x64). Если необходимо статически инструментировать любой модуль .NET, используйте instrument команду (с соответствующим параметром идентификатора сеанса) перед выполнением connect команды.

Краткие сведения

dotnet-coverage connect
    [-b|--background] [-t|--timeout]
    [-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
    <session>
    <command> <args>

Аргументы

  • <session>

    Идентификатор сеанса сервера, размещенного командой collect .

  • <command>

    Команда, для которой должны быть собраны данные об объеме протестированного кода.

  • <args>

    Аргументы командной строки для команды.

Параметры

  • -b|--background

    Запускает клиент в новом фоновом процессе.

  • -t|--timeout

    Время ожидания (в миллисекундах) для взаимодействия между клиентом и сервером.* -l|--log-file <log-file>

  • -l|--log-file <log-file>

    Установка пути к файлу журнала. Когда вы указываете каталог (с разделителем пути в конце), создается новый файл журнала для каждого процесса в изучаемой области.

  • -ll|--log-level <log-level>

    Задает уровень ведения журнала. Поддерживаемые значения: Error, Info и Verbose.

моментальный снимок dotnet-coverage

Создает файл покрытия для существующей коллекции покрытия кода.

Краткие сведения

dotnet-coverage snapshot
    [-r|--reset]
    [-o|--output <output>]
    [-tn|--tag-name <tag-name>] [-tid|--tag-identifier <tag-identifier>]
    [-t|--timeout]
    [-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
    <session>

Аргументы

  • <session>

    Идентификатор сеанса коллекции, для которой создается файл покрытия.

Параметры

  • -r|--reset <reset>

    Очищает существующие сведения о охвате после создания файла покрытия.

  • -o|--output <output>

    Задает выходной файла отчета об объеме протестированного кода. Если он не указан, он создается автоматически с меткой времени.

  • -tn|--tag-name <tag-name>

    Создает имя тега моментального снимка в файле покрытия с текущими сведениями о охвате. Имя тега и идентификатор тега являются взаимоключающими.

  • -tid|--tag-identifier <tag-identifier>

    Создает идентификатор тега моментального снимка в файле покрытия с текущими сведениями о охвате. Имя тега и идентификатор тега являются взаимоключающими.

  • -t|--timeout

    Время ожидания (в миллисекундах) для взаимодействия между клиентом и сервером.

  • -l|--log-file <log-file>

    Установка пути к файлу журнала. Когда вы указываете каталог (с разделителем пути в конце), создается новый файл журнала для каждого процесса в изучаемой области.

  • -ll|--log-level <log-level>

    Задает уровень ведения журнала. Поддерживаемые значения: Error, Info и Verbose.

dotnet-coverage shutdown

Прекращение сбора сведений о текущем объеме протестированного кода.

Краткие сведения

dotnet-coverage shutdown
    [-t|--timeout]
    [-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
    <session>

Аргументы

  • <session>

    Идентификатор закрываемого сеанса сбора данных.

Параметры

  • -t|--timeout

    Время ожидания (в миллисекундах) для взаимодействия с сервером.

  • -l|--log-file <log-file>

    Установка пути к файлу журнала. Когда вы указываете каталог (с разделителем пути в конце), создается новый файл журнала для каждого процесса в изучаемой области.

  • -ll|--log-level <log-level>

    Задает уровень ведения журнала. Поддерживаемые значения: Error, Info и Verbose.

инструмент dotnet-coverage

Команда инструментирования используется для инструментирования двоичного файла на диске.

Краткие сведения

dotnet-coverage instrument
    [-s|--settings <settings>] [-id|--session-id <session-id>]
    [-o|--output <output>] [-l|--log-file <log-file>]
    [-ll|--log-level <log-level>] [-?|-h|--help]
    <input-file>

Аргументы

  • <input-file>

    Входной двоичный файл.

Параметры

  • -s|--settings <settings>

    Задает путь к параметрам покрытия кода XML.

  • -id|--session-id <session-id>

    Задает идентификатор сеанса для объема протестированного кода. Если этот параметр не указан, средство создаст случайный идентификатор GUID.

  • -o|--output <output>

    Задает путь к двоичному файлу вывода. Если это не указано, инструментирование будет выполняться на месте.

  • -l|--log-file <log-file>

    Установка пути к файлу журнала. Когда вы указываете каталог (с разделителем пути в конце), создается новый файл журнала для каждого процесса в изучаемой области.

  • -ll|--log-level <log-level>

    Задает уровень ведения журнала. Поддерживаемые значения: Error, Info и Verbose.

Примеры сценариев

Сбор данных об объеме протестированного кода

Сбор данных об объеме протестированного кода для любого приложения .NET (например, консольного приложения или приложения Blazor) выполняется с помощью следующей команды:

dotnet-coverage collect dotnet run

Если приложению для прекращения работы требуется сигнал, можно использовать сочетание клавиш CTRL+C, которое позволит вам по-прежнему получать сведения об объеме протестированного кода. В качестве аргумента можно указать любую команду, которая в конечном итоге запустит приложение .NET. Например, это может быть скрипт PowerShell.

Сеансы

При анализе объема протестированного кода на сервере .NET, который просто ожидает поступления сообщений и отправляет ответы, нужна возможность остановить его работу, чтобы получить итоговые результаты сбора данных об объеме протестированного кода. Локально можно использовать сочетание клавиш Ctrl+C, но это не работает в Azure Pipelines. В таких ситуациях можно использовать сеансы. Можно указать идентификатор сеанса при запуске сбора данных, а затем командой shutdown завершить сбор данных и остановить работу сервера.

Например, предположим, что у вас есть сервер в каталоге D:\serverexample\server и тестовый проект в каталоге D:\serverexample\tests. Тесты взаимодействуют с сервером через сеть. Вы можете запустить сбор информации об объеме протестированного кода для сервера следующим образом:

D:\serverexample\server> dotnet-coverage collect --session-id serverdemo "dotnet run"

Указан идентификатор сеанса serverdemo. Затем можно запустить тесты следующим образом:

D:\serverexample\tests> dotnet test

Файл покрытия кода для сеанса serverdemo можно создать с текущим покрытием следующим образом:

dotnet-coverage snapshot --output after_first_test.coverage serverdemo

Кроме того, тег моментального снимка можно добавить в файл покрытия с помощью параметров тега следующим образом:

dotnet-coverage snapshot --tag-name after_first_test --tag-identifier after_first_test serverdemo

Наконец, можно остановить сеанс serverdemo и работу сервера следующим образом:

dotnet-coverage shutdown serverdemo

Вот пример полных выходных данных на стороне сервера:

D:\serverexample\server> dotnet-coverage collect --session-id serverdemo "dotnet run"
SessionId: serverdemo
Waiting for a connection... Connected!
Received: Hello!
Sent: HELLO!
Waiting for a connection... Code coverage results: output.coverage.
D:\serverexample\server>

Режим сервера и клиента

Сбор покрытия кода также можно выполнить в режиме сервера-клиента. В этом сценарии запускается сервер сбора кода, и несколько клиентов могут подключаться к серверу. Покрытие кода собирается для всех клиентов коллективно.

Запустите сервер покрытия кода с помощью следующей команды:

dotnet-coverage collect --session-id serverdemo --server-mode

В этом примере идентификатор сеанса был указан как serverdemo для сервера. Клиент может подключиться к серверу с помощью этого идентификатора сеанса с помощью следующей команды:

dotnet-coverage connect serverdemo dotnet run

Наконец, можно закрыть сеанс serverdemo и сервер с помощью следующей команды:

dotnet-coverage shutdown serverdemo

Процесс сервера создает общий отчет о охвате кода для всех клиентов и завершает работу.

Вот пример полных выходных данных на стороне сервера:

D:\serverexample\server> dotnet-coverage collect --session-id serverdemo --server-mode
SessionId: serverdemo
// Server will be in idle state and wait for connect and shutdown commands
Code coverage results: output.coverage.
D:\serverexample\server>

Ниже приведен пример полного вывода на стороне клиента:

D:\serverexample\server> dotnet-coverage connect serverdemo ConsoleApplication.exe World
Hello World!!
D:\serverexample\server> dotnet-coverage connect serverdemo WpfApplication.exe
D:\serverexample\server> dotnet-coverage shutdown serverdemo
D:\serverexample\server>

Вы также можете запустить сервер и клиент в фоновом режиме. Другой процесс начинается в фоновом режиме и возвращает элемент управления пользователю.

Ниже приведен пример полного вывода в режиме клиента фонового сервера:

D:\serverexample\server> dotnet-coverage collect --session-id serverdemo --server-mode --background
D:\serverexample\server> dotnet-coverage connect --background serverdemo ConsoleApplication.exe World
D:\serverexample\server> dotnet-coverage connect --background serverdemo WpfApplication.exe
D:\serverexample\server> dotnet-coverage shutdown serverdemo
D:\serverexample\server>

Покрытие статического кода для управляемых сборок

Средство dotnet-coverage можно использовать для сбора покрытия кода для управляемых сборок с помощью статического инструментирования. Существует три различных способа. Чтобы продемонстрировать, предположим, что у нас есть простое консольное приложение C#:

D:\examples\ConsoleApp> dotnet run
Hello, World!

Использование команды сбора с параметром или конфигурацией для включения файлов

Если вы не хотите использовать instrument команду, файлы, которые нужно инструментировать, можно указать с помощью --include-files следующего варианта:

D:\examples\ConsoleApp> dotnet-coverage collect --include-files .\bin\Debug\net7.0\*.dll dotnet run
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.

SessionId: 57862ec0-e512-49a5-8b66-2804174680fc
Hello, World!
Code coverage results: output.coverage.

Вы также можете указать файлы для инструментирования с помощью конфигурации следующим образом:

<ModulePaths>
  <IncludeDirectories>
    <Directory>D:\examples\ConsoleApp\bin\Debug\net7.0</Directory>
  </IncludeDirectories>
</ModulePaths>

Использование команд instrument и collect

В этом случае необходимо инструментировать первый двоичный файл:

D:\examples\ConsoleApp> dotnet-coverage instrument .\bin\Debug\net7.0\ConsoleApp.dll
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.

Input file successfully instrumented.

Затем можно собирать данные об объеме протестированного кода следующим образом:

D:\examples\ConsoleApp> dotnet-coverage collect .\bin\Debug\net7.0\ConsoleApp.exe
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.

SessionId: a09e6bef-ff64-4b5f-8bb8-fc495ebb50ba
Hello, World!
Code coverage results: output.coverage.

Использование инструментирования и сбора команд в режиме сервера

В этом случае можно полностью отделить сбор данных о протестированном объеме от запуска приложения. Сначала инструментируйте двоичный файл следующим образом:

D:\examples\ConsoleApp> dotnet-coverage instrument --session-id 73c34ce5-501c-4369-a4cb-04d31427d1a4 .\bin\Debug\net7.0\ConsoleApp.dll
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.

Input file successfully instrumented.

Примечание.

В этом сценарии необходимо использовать идентификатор сеанса, чтобы убедиться, что приложение может подключаться к внешнему сборщику и предоставлять данные.

На втором шаге необходимо запустить сборщик данных о протестированном объеме:

D:\examples\ConsoleApp> dotnet-coverage collect --session-id 73c34ce5-501c-4369-a4cb-04d31427d1a4 --server-mode
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.

SessionId: 73c34ce5-501c-4369-a4cb-04d31427d1a4

Затем приложение можно запустить следующим образом:

D:\examples\ConsoleApp> .\bin\Debug\net7.0\ConsoleApp.exe
Hello, World!

Теперь сборщик можно закрыть:

D:\examples\ConsoleApp> dotnet-coverage shutdown 73c34ce5-501c-4369-a4cb-04d31427d1a4
Microsoft (R) Code Coverage Command Line Tool (x64)
Copyright (c) Microsoft Corporation. All rights reserved.

Настройки

При использовании команды collect вы можете указать файл с параметрами. С помощью файла параметров можно исключать некоторые модули или методы из анализа объема протестированного кода. Используется тот же формат, что и в конфигурации сборщика данных в файле runsettings. См. дополнительные сведения по настройке анализа объема протестированного кода. Приведем пример:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
    <CodeCoverage>
        <!--
        Additional paths to search for .pdb (symbol) files. Symbols must be found for modules to be instrumented.
        If .pdb files are in the same folder as the .dll or .exe files, they are automatically found. Otherwise, specify them here.
        Note that searching for symbols increases code coverage run time. So keep this small and local.
        -->
        <SymbolSearchPaths>
            <Path>C:\Users\User\Documents\Visual Studio 2012\Projects\ProjectX\bin\Debug</Path>
            <Path>\\mybuildshare\builds\ProjectX</Path>
        </SymbolSearchPaths>

        <!--
        About include/exclude lists:
        Empty "Include" clauses imply all; empty "Exclude" clauses imply none.
        Each element in the list is a regular expression (ECMAScript syntax). See /visualstudio/ide/using-regular-expressions-in-visual-studio.
        An item must first match at least one entry in the include list to be included.
        Included items must then not match any entries in the exclude list to remain included.
        -->

        <!-- Match assembly file paths: -->
        <ModulePaths>
            <Include>
                <ModulePath>.*\.dll$</ModulePath>
                <ModulePath>.*\.exe$</ModulePath>
            </Include>
            <Exclude>
                <ModulePath>.*CPPUnitTestFramework.*</ModulePath>
            </Exclude>
            <!-- Additional directories from .NET assemblies should be statically instrumented: -->
            <IncludeDirectories>
                <Directory Recursive="true">C:\temp</Directory>
            </IncludeDirectories>
        </ModulePaths>

        <!-- Match fully qualified names of functions: -->
        <!-- (Use "\." to delimit namespaces in C# or Visual Basic, "::" in C++.)  -->
        <Functions>
            <Exclude>
                <Function>^Fabrikam\.UnitTest\..*</Function>
                <Function>^std::.*</Function>
                <Function>^ATL::.*</Function>
                <Function>.*::__GetTestMethodInfo.*</Function>
                <Function>^Microsoft::VisualStudio::CppCodeCoverageFramework::.*</Function>
                <Function>^Microsoft::VisualStudio::CppUnitTestFramework::.*</Function>
            </Exclude>
        </Functions>

        <!-- Match attributes on any code element: -->
        <Attributes>
            <Exclude>
            <!-- Don't forget "Attribute" at the end of the name -->
                <Attribute>^System\.Diagnostics\.DebuggerHiddenAttribute$</Attribute>
                <Attribute>^System\.Diagnostics\.DebuggerNonUserCodeAttribute$</Attribute>
                <Attribute>^System\.CodeDom\.Compiler\.GeneratedCodeAttribute$</Attribute>
                <Attribute>^System\.Diagnostics\.CodeAnalysis\.ExcludeFromCodeCoverageAttribute$</Attribute>
            </Exclude>
        </Attributes>

        <!-- Match the path of the source files in which each method is defined: -->
        <Sources>
            <Exclude>
                <Source>.*\\atlmfc\\.*</Source>
                <Source>.*\\vctools\\.*</Source>
                <Source>.*\\public\\sdk\\.*</Source>
                <Source>.*\\microsoft sdks\\.*</Source>
                <Source>.*\\vc\\include\\.*</Source>
            </Exclude>
        </Sources>

        <!-- Match the company name property in the assembly: -->
        <CompanyNames>
            <Exclude>
                <CompanyName>.*microsoft.*</CompanyName>
            </Exclude>
        </CompanyNames>

        <!-- Match the public key token of a signed assembly: -->
        <PublicKeyTokens>
            <!-- Exclude Visual Studio extensions: -->
            <Exclude>
                <PublicKeyToken>^B77A5C561934E089$</PublicKeyToken>
                <PublicKeyToken>^B03F5F7F11D50A3A$</PublicKeyToken>
                <PublicKeyToken>^31BF3856AD364E35$</PublicKeyToken>
                <PublicKeyToken>^89845DCD8080CC91$</PublicKeyToken>
                <PublicKeyToken>^71E9BCE111E9429C$</PublicKeyToken>
                <PublicKeyToken>^8F50407C4E9E73B6$</PublicKeyToken>
                <PublicKeyToken>^E361AF139669C375$</PublicKeyToken>
            </Exclude>
        </PublicKeyTokens>

        <EnableStaticManagedInstrumentation>True</EnableStaticManagedInstrumentation>
        <EnableDynamicManagedInstrumentation>True</EnableDynamicManagedInstrumentation>

    </CodeCoverage>
</Configuration>

Объединение отчетов об объеме протестированного кода

Вы можете объединить a.coverage и b.coverage, а также сохранить данные в merged.coverage следующим образом:

dotnet-coverage merge -o merged.coverage a.coverage b.coverage

Например, при выполнении такой команды, как dotnet test --collect "Code Coverage", отчет об объеме протестированного кода сохраняется в папке, в качестве имени которой используется случайный идентификатор GUID. Такие папки трудно найти и объединить. С помощью этого средства можно объединить все отчеты о охвате кода для всех проектов с помощью шаблонов глоббинга следующим образом:

dotnet-coverage merge -o merged.cobertura.xml -f cobertura **\*.coverage

Предыдущая команда объединяет все отчеты об объеме протестированного кода из текущего каталога и всех подкаталогов, а затем сохраняет результат в файле cobertura. В Azure Pipelines вы можете опубликовать объединенный отчет cobertura с помощью задачи "Публикация результатов проверки объема протестированного кода".

Для преобразования отчета об объеме протестированного кода в другой формат можно использовать команду merge. Например, следующая команда позволяет преобразовать отчет об объеме протестированного двоичного кода в формат XML.

dotnet-coverage merge -o output.xml -f xml input.coverage

См. также