MTP 서버 모드를 사용하면 편집기, IDE, 사용자 지정 테스트 UI 또는 기타 테스트 도구가 테스트 애플리케이션을 시작하고 JSON-RPC를 통해 검색 및 실행을 구동할 수 있습니다. 도구에서 터미널 출력을 구문 분석하지 않고도 테스트 메타데이터, 선택한 테스트의 실행, 진행률 업데이트 또는 결과 아티팩트가 필요하다면 서버 모드를 사용하세요. 일반 명령줄 및 CI 실행의 경우 테스트 애플리케이션을 직접 실행하거나 사용합니다 dotnet test.
지속 연결 없이 단발성 검색을 수행하려면 --list-tests json를 사용합니다. 기존 VSTest 클라이언트는 프로그래밍 방식 테스트 검색 및 실행을 참조하세요.
--server 또는 --server jsonrpc로 공용 JSON-RPC 서버를 시작합니다.
Important
.NET SDK는 별도의 내부 이진 프로토콜을 사용합니다--server dotnettestcli. 그 가치를 직접 전달하지 마십시오.
dotnet test 는 전송 및 프로토콜 인수를 구성합니다.
원본 전용 클라이언트 사용
MTP 2.4는 정식 JSON-RPC 클라이언트를 제공합니다. Microsoft.Testing.Platform.ServerMode.Client.Sources 패키지를 추가합니다. 패키지는 런타임 어셈블리를 추가하는 대신 C# 원본을 프로젝트에 삽입합니다.
원본 전용 디자인은 다음을 제공합니다.
- 런타임 DLL 또는 추가 배포 종속성이 없습니다.
- 네이티브 AOT 호환, 리플렉션 없는 직렬화
- MTP 서버와 동일한 리포지토리의 프로토콜 형식 및 serialization 코드입니다.
삽입된 MtpServerClientIMtpServerClient프로토콜 유형은 연결을 초기화하고, 테스트를 검색하고, 테스트를 실행하고, 서버 종료를 요청하고, 테스트 노드 업데이트를 보고할 수 있습니다. 삽입된 모든 형식은 사용하는 어셈블리에는 internal 상태로 유지됩니다. 클라이언트는 프로세스 시작, 전송, 메시지 프레이밍 및 직렬화를 처리합니다. JSON-RPC를 직접 구현할 필요가 없습니다.
패키지는 C# 원본을 컴파일합니다. Visual Basic 또는 다른 .NET 언어에서 클라이언트를 사용하려면 다음 예제와 같이 삽입된 형식을 둘러싸는 자체 public API를 노출하는 C# 클래스 라이브러리를 참조하세요.
.NET에서 테스트 검색 및 실행
이 예제에서는 원본 전용 클라이언트 패키지 버전 2.5.2를 사용하고 .NET 10을 대상으로 합니다. 먼저 MTP 지원 테스트 애플리케이션을 빌드한 다음 빌드된 .dll 또는 실행 파일의 경로를 클라이언트에 전달합니다.
공유 C# 도우미는 테스트를 검색하고, 각 노드의 직렬화 가능한 메타데이터를 인쇄하고, UID에서 검색된 테스트를 실행합니다. 하위 집합을 실행하려면 검색 업데이트에서 필요한 UID를 선택하고 RunTestsAsync에 해당 UID만 전달하세요. 표시 이름을 테스트 ID로 사용하지 마세요.
using System.Text.Json;
using Microsoft.Testing.Platform.ServerMode.Client;
namespace TestClientSample;
public static class TestClient
{
public static async Task<int> DiscoverAndRunAsync(
string testApplicationPath,
CancellationToken cancellationToken = default)
{
string path = Path.GetFullPath(testApplicationPath);
var testUids = new HashSet<string>(StringComparer.Ordinal);
using (IMtpServerClient client = await MtpServerClient.LaunchAsync(
path, cancellationToken: cancellationToken))
{
try
{
MtpServerCapabilities capabilities =
await client.InitializeAsync(cancellationToken);
if (capabilities.MultiConnectionProvider)
{
throw new NotSupportedException("A passive controller connection can't discover or run tests.");
}
if (!capabilities.SupportsDiscovery)
{
throw new NotSupportedException("The test application doesn't support discovery.");
}
client.LogReceived += (_, log) => Console.Error.WriteLine(log.Message);
client.TestNodesUpdated += (_, update) =>
{
foreach (MtpTestNodeUpdate change in update.Changes)
{
Console.WriteLine(JsonSerializer.Serialize(change.Node));
if (change.NodeType != "group"
&& change.ExecutionState == "discovered"
&& change.Uid is string uid)
{
testUids.Add(uid);
}
}
};
await client.DiscoverTestsAsync(cancellationToken);
await client.ExitAsync(cancellationToken);
}
finally
{
await client.ShutdownAsync();
}
}
if (testUids.Count == 0)
{
Console.Error.WriteLine("No tests were discovered.");
return 8;
}
var completedUids = new HashSet<string>(StringComparer.Ordinal);
bool hasUnsuccessfulResult = false;
using IMtpServerClient runClient = await MtpServerClient.LaunchAsync(
path, cancellationToken: cancellationToken);
try
{
MtpServerCapabilities capabilities =
await runClient.InitializeAsync(cancellationToken);
if (capabilities.MultiConnectionProvider)
{
throw new NotSupportedException("A passive controller connection can't discover or run tests.");
}
runClient.LogReceived += (_, log) => Console.Error.WriteLine(log.Message);
runClient.TestNodesUpdated += (_, update) =>
{
foreach (MtpTestNodeUpdate change in update.Changes)
{
Console.WriteLine(JsonSerializer.Serialize(change.Node));
if (change.Uid is string uid
&& testUids.Contains(uid)
&& change.ExecutionState is string state
&& state is not ("discovered" or "in-progress")
&& (!change.Node.TryGetValue("retry.is-superseded", out object? superseded)
|| superseded is not true))
{
completedUids.Add(uid);
hasUnsuccessfulResult |= state is not ("passed" or "skipped");
}
}
};
MtpRunResult result = await runClient.RunTestsAsync(testUids, cancellationToken);
foreach (MtpAttachment artifact in result.Artifacts)
{
Console.WriteLine($"Artifact: {artifact.Uri}");
}
await runClient.ExitAsync(cancellationToken);
if (hasUnsuccessfulResult || !testUids.All(completedUids.Contains))
{
Console.Error.WriteLine("A selected test failed or didn't report a final result.");
return 2;
}
return 0;
}
finally
{
await runClient.ShutdownAsync();
}
}
}
도우미는 검색 및 실행을 위해 별도의 테스트 프로세스를 시작하므로 MtpServerCapabilities.MultiRequestSupport이 필요하지 않습니다. 프로세스를 다시 사용하려면 여러 요청을 실행하기 전에 InitializeAsync 후에 해당 기능을 확인하세요. 또한 디스커버리를 요청하기 전에 SupportsDiscovery도 확인하세요.
Important
원본 전용 클라이언트의 실행 헬퍼는 하나의 JSON-RPC 연결을 관리합니다. 버전 2.5.2에서는 컨트롤러 지원 확장에서 사용하는 추가 연결을 수락하고 라우팅하지 않습니다. 예를 들어 Windows에 대한 TRX 보고 기능은 활성 테스트 호스트 전에 수동 연결이 도착하는 컨트롤러를 시작할 수 있습니다.
true이(가) MultiConnectionProvider로 설정된 연결은 업데이트 및 아티팩트만 푸시하므로, 해당 연결에 검색 또는 실행 요청을 보내지 마세요. 이 예제에서는 해당 연결을 거부합니다.
컨트롤러 지원 보고서의 경우 CLI 또는 dotnet test를 통해 테스트 애플리케이션을 실행하거나, 프로토콜의 추가 연결을 처리하는 도구 클라이언트를 사용합니다. 단일 연결 클라이언트는 활성 테스트 호스트가 게시하는 아티팩트를 계속 받을 수 있습니다.
C# 및 Visual Basic 콘솔 프로젝트는 모두 C# 도우미 프로젝트를 참조합니다.
using TestClientSample;
if (args.Length != 1)
{
Console.Error.WriteLine("Usage: DiscoverAndRun <test-application-path>");
return 1;
}
return await TestClient.DiscoverAndRunAsync(args[0]);
테스트 애플리케이션 경로를 인수로 사용하여 두 콘솔 프로젝트 중 하나를 실행합니다.
dotnet run --project <client-project> -- <test-application-path>
이 예제는 선택한 모든 UID에 최종 결과가 있고 대체되지 않은 모든 최종 결과 보고서가 8 또는 0를 보고할 때 2를 반환하며, 성공하지 못했거나 누락된 최종 결과에는 skipped, 검색에서 테스트를 반환하지 않으면 passed를 반환합니다. 이러한 결정은 샘플 클라이언트의 것입니다. 완료된 RunTestsAsync 작업은 테스트가 통과한 것이 아니라 프로토콜 요청이 완료되었음을 의미합니다.
MtpRunResult.Artifacts 에는 통과/실패 평결이 아닌 실행 아티팩트가 포함됩니다. 테스트 노드 업데이트를 사용하여 테스트 결과를 판정합니다.
여러 결과가 UID를 공유할 수 있습니다. 이 예제에서는 retry.is-superseded이 true인 경우에만 이전 재시도 시도를 무시합니다. UID가 같다고 해서 재시도가 성립하는 것은 아닙니다. 나중에 전달되거나 건너뛴 결과는 이전의 대체되지 않은 오류를 지울 수 없습니다.
업데이트 및 메타데이터 수신
탐색 또는 실행 전에 TestNodesUpdated 구독하세요. 각 업데이트에서 Changes를 읽고, Uid로 노드를 식별합니다. 클라이언트는 ExecutionState, ErrorMessage, DurationInMilliseconds 및 DisplayName와 같은 편리한 속성을 제공합니다.
Node 및 프레임워크별 속성과 같은 다른 직렬화된 필드에 대해서는 사전을 참조하세요.
MSTest는 테스트 범주 및 사용자 지정 TestProperty 값을 특성으로 게시합니다. 메타데이터 가용성은 테스트 프레임워크 및 검색 중에 게시되는 내용에 따라 달라집니다. 임의 특성 및 메모리 내 IProperty 구현은 프로세스 경계를 자동으로 넘지 않습니다. 이식 가능한 키-값 메타데이터를 게시하려면 공용 TestMetadataProperty 형식을 사용합니다. 플랫폼 및 호환성 계층은 다른 직렬화 가능한 필드를 제공할 수 있습니다. 내부 속성 형식은 확장 API가 아닙니다. 자세한 내용은 테스트 노드 속성을 참조하세요.
JSON-RPC 노드 사전이 --list-tests json 문서와 일치할 것으로 예상하지 않습니다. 전송 계층은 서로 다른 필드 레이아웃을 사용합니다. 또한 모든 프레임워크가 VSTest 관련 vstest.* 필드를 내보낸다고 가정하지 마세요.
클라이언트는 업데이트를 순서대로 처리하고 검색 또는 실행 작업이 완료되기 전에 해당 처리기를 호출합니다. 최종 업데이트를 기다리기 위해 대기 시간은 필요하지 않습니다. 핸들러는 클라이언트의 읽기 루프에서 동기적으로 실행되므로, 이를 블로킹하거나 다른 클라이언트 작업을 동기적으로 대기하지 마세요. 비용이 많이 드는 작업 또는 UI 업데이트를 적절한 스레드로 디스패치합니다.
프로토콜을 통해 취소를 요청하려면 검색 또는 실행 메서드에 취소 토큰을 전달하세요. 테스트 프레임워크에서 트리 필터를 지원하는 경우 먼저 UID 컬렉션을 만들지 않고 MTP 트리 필터 식과 함께 DiscoverTestsWithFilterAsync 또는 RunTestsWithFilterAsync을 사용하여 테스트를 선택합니다. 이러한 메서드는 VSTest --filter 식을 허용하지 않습니다.
클라이언트 요구 사항 충족
C# 12 이상을 사용합니다. 패키지는 프로젝트의 언어 버전 설정을 준수합니다. 대상 프레임워크의 기본값이 이전 C# 버전이면 LangVersion를 12.0 이상으로 설정하세요. 이 패키지는 .NET Framework 4.6.2 및 netstandard2.0에 대한 내부 호환성 유형도 제공합니다.
중복된 내부 형식을 방지하기 위해 패키지를 추가하기 전에 MTP 클라이언트의 손으로 쓴 복사본을 제거합니다.
시작 모델 선택
테스트 애플리케이션을 외부 프로세스로 시작하려면 .를 사용합니다 MtpServerClient.LaunchAsync. 클라이언트는 해당 자식 프로세스를 관리하며, 필요할 경우 정리 과정에서 이를 종료합니다.
특정 환경에 대한 외부 테스트 애플리케이션을 구성하려면 시작하기 전에 MtpServerClientOptions.EnvironmentVariables을(를) 설정합니다. 자식 프로세스는 부모의 환경을 상속하며, 제공된 값은 자식 프로세스에 적용됩니다. 이러한 옵션은 인프로세스 호스트의 환경을 변경하지 않습니다.
각 클라이언트는 하나의 테스트 애플리케이션을 제어합니다. 여러 테스트 애플리케이션이 있는 경우, 각 애플리케이션별로 클라이언트를 생성하고 사용 중인 도구에서 그 결과를 집계하세요.
Process.Start를 사용할 수 없는 임베디드 호스트 또는 UI 스레드 환경의 경우 MtpServerClient.LaunchInProcessAsync를 사용하세요. 메서드는 현재 프로세스에서 비동기 콜백을 통해 테스트 애플리케이션을 실행합니다. 콜백과 클라이언트가 프로세스를 공유하므로 시작 스레드를 차단하지 마세요.
두 시작 모델 모두 루프백 TCP 전송을 사용합니다. 브라우저의 WebAssembly는 필요한 리스너를 만들 수 없으므로 in-process 시작 시 PlatformNotSupportedException 예외가 발생합니다. 동일 프로세스 실행은 WebAssembly에 대한 대체 전송 방식을 제공하지 않습니다.
클라이언트 종료
호출 스레드를 차단하지 않고 클라이언트를 해체하고 애플리케이션을 시작하려면 .를 호출합니다 IMtpServerClient.ShutdownAsync(). 비동기 메서드는 포함된 호스트에서 UI 스레드 응답성 및 교착 상태 문제를 방지합니다.
인프로세스 호스트의 경우 MtpServerClientOptions.ServerShutdownTimeout는 클라이언트가 전송을 닫은 후 분해가 얼마나 오래 대기할지 제어합니다. 기본값은 30초입니다. 종료 후 읽어 ServerExitCode 콜백의 종료 코드를 가져옵니다. 이 값은 애플리케이션이 실행되는 동안 또는 종료 코드를 반환하는 대신 애플리케이션이 실패할 때 유지 null 됩니다.
클라이언트 상태 유지 선언
MTP 2.4.1부터 nullable MtpServerClientOptions.IsStateful 옵션을 설정합니다. 이 옵션은 클라이언트가 테스트 노드 업데이트를 사용하는 방식을 설명합니다.
| Value | 선언 |
|---|---|
true |
클라이언트는 세션에 대한 주소 지정 가능한 테스트 노드 집합을 유지하고 IDE 테스트 탐색기처럼 다른 업데이트가 변경될 때까지 각 노드의 마지막으로 알려진 상태를 유지합니다. |
false |
클라이언트는 해당 테스트 노드 상태를 유지하지 않고 업데이트를 수신합니다. |
null(기본값) |
클라이언트는 capability를 선언하지 않습니다. 초기화 핸드셰이크는 필드를 생략합니다. |
클라이언트는 실험적 capabilities.testing.isStateful 프로토콜 기능을 통해 명시적 부울 값을 보냅니다. 상태 유지 속성은 연결 수명 및 서버의 MultiRequestSupport 기능과 독립적입니다. 클라이언트는 동일한 연결을 통해 여러 요청을 보낸다고 해서 단순히 상태 저장이 되지 않습니다.
MTP 2.4.0은 기본값이 false인 null을 허용하지 않는 부울 옵션을 사용합니다. 선언되지 않은 capability를 유지하려면 MTP 2.4.1 이상을 사용하세요.
프레임워크 또는 확장 내에서 실험적 IClientInfo 서비스를 사용하여 선언을 검사합니다. 기능이 선언되지 않은 경우 clientInfo.Capabilities.IsStateful인 보수적인 부울 결과는 false를 참조하세요. MTP 2.4.1 이상에서는 ClientCapabilitiesExtensions.GetIsStateful()가 선언되지 않은 클라이언트, 명시적으로 무상태인 클라이언트, 상태 저장 클라이언트를 구분합니다.
프로토콜 호환성 협상
MTP 2.4부터 서버 모드 프로토콜 협상은 MTP NuGet 패키지 버전과 독립적입니다. 클라이언트는 지원하는 프로토콜 버전을 선언하고 서버는 일반 버전을 선택합니다. 지원되는 버전 간에 겹치는 부분이 없으면 테스트 애플리케이션은 호환되지 않는 와이어 계약으로 계속 진행하는 대신 12 종료 코드(ProtocolError)와 함께 종료됩니다.
버전이 지정된 서버 모드 1.0 JSON 스키마 를 사용하여 메시지의 유효성을 검사합니다. System.Text.Json과 Jsonite 직렬화기는 동일한 스키마와 오류 형식을 사용합니다.
참고하십시오
.NET