如何用 CapSkip 在 xUnit 测试中识别验证码（C#）

# The SDK has no xUnit v3 template until you install the template pack.
dotnet new install xunit.v3.templates
dotnet new xunit3 -n CapSkipTests -f net10.0
cd CapSkipTests
rm UnitTest1.cs          # the template's sample test; delete it
dotnet add package CapSkip

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

// CapSkipFixture.cs
using CapSkip;

public sealed partial class CapSkipFixture : IAsyncLifetime
{
    // The SDK never reads CAPSKIP_* itself, so read them here.
    private static string Env(string name, string fallback) =>
        Environment.GetEnvironmentVariable(name) ?? fallback;

    private readonly string _host = Env("CAPSKIP_HOST", "127.0.0.1");
    private readonly int _port = int.Parse(Env("CAPSKIP_PORT", "8080"));

    public CapSkipClient Solver { get; }
    public bool IsUp { get; private set; }
    public string SiteUrl { get; } = Env("STAGING_URL", "https://staging.example.com");

    public CapSkipFixture() => Solver = new CapSkipClient(
        apiKey: Env("CAPSKIP_API_KEY", "capskip"), host: _host, port: _port);

    public async ValueTask InitializeAsync() =>
        IsUp = await CapSkipProbe.IsListeningAsync(_host, _port);

    public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}

// CapSkipProbe.cs
using System.Net.Sockets;

public static class CapSkipProbe
{
    // A TCP connect asks "is anything listening?" and sends no solve job.
    public static async Task<bool> IsListeningAsync(string host, int port)
    {
        using var tcp = new TcpClient();
        using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(1));
        try
        {
            await tcp.ConnectAsync(host, port, timeout.Token);
            return true;
        }
        catch (Exception e) when (e is SocketException or OperationCanceledException)
        {
            return false;
        }
    }
}

// AssemblyInfo.cs
// One CapSkipFixture for the whole run, handed to every test class
// through its constructor. No IClassFixture or [Collection] needed.
[assembly: AssemblyFixture(typeof(CapSkipFixture))]

// SignupSite.cs
using System.Text.RegularExpressions;

public sealed record SignupPage(string Url, string SiteKey, string Csrf);

public sealed partial class SignupSite(string baseUrl) : IDisposable
{
    // One HttpClient per test: it keeps this test's cookies and no
    // other test's.
    private readonly HttpClient _http = new();

    public async Task<SignupPage> OpenAsync(CancellationToken ct)
    {
        var url = baseUrl + "/signup";
        var html = await _http.GetStringAsync(url, ct);
        return new SignupPage(url,
            Regex.Match(html, "data-sitekey=\"([^\"]+)\"").Groups[1].Value,
            Regex.Match(html, "name=\"csrfmiddlewaretoken\" value=\"([^\"]+)\"").Groups[1].Value);
    }

    public void Dispose() => _http.Dispose();
}

// SignupSite.Submit.cs
using System.Net;

public sealed partial class SignupSite
{
    public async Task<(HttpStatusCode Status, string Body)> SubmitAsync(
        SignupPage page, string token, CancellationToken ct)
    {
        using var request = new HttpRequestMessage(HttpMethod.Post, page.Url)
        {
            Content = new FormUrlEncodedContent(new Dictionary<string, string>
            {
                ["csrfmiddlewaretoken"] = page.Csrf,
                ["username"] = "ci-user",
                ["g-recaptcha-response"] = token,
            }),
        };
        request.Headers.Referrer = new Uri(page.Url); // HttpClient sends none
        using var response = await _http.SendAsync(request, ct);
        return (response.StatusCode, await response.Content.ReadAsStringAsync(ct));
    }
}

// SignupTests.cs
using System.Net;

public class SignupTests(CapSkipFixture capskip)
{
    [Fact(Timeout = 120_000)] // milliseconds; also cancels the test's token
    public async Task Signup_with_a_solved_captcha_is_accepted()
    {
        Assert.SkipUnless(capskip.IsUp, "CapSkip is not running");
        var ct = TestContext.Current.CancellationToken;
        using var site = new SignupSite(capskip.SiteUrl);

        var page = await site.OpenAsync(ct);
        var solved = await capskip.Solver.RecaptchaAsync(
            page.SiteKey, page.Url, cancellationToken: ct);
        var (status, body) = await site.SubmitAsync(page, solved.Code, ct);

        Assert.Contains("welcome", body); // on failure xUnit prints the site's reason
        Assert.Equal(HttpStatusCode.OK, status);
    }
}

# PowerShell. The fixture reads these; unset ones fall back to the defaults.
$env:CAPSKIP_HOST    = "127.0.0.1"    # a Server mode machine: its LAN IP
$env:CAPSKIP_PORT    = "8080"
$env:CAPSKIP_API_KEY = "capskip"
$env:STAGING_URL     = "https://staging.example.com"
dotnet test

{
  "$schema": "https://xunit.net/schema/current/xunit.runner.schema.json",
  "maxParallelThreads": 8
}

// CapSkipFixture.Gate.cs
using CapSkip;

public sealed partial class CapSkipFixture
{
    // One gate for the whole run (that is why it lives in the assembly
    // fixture): at most 8 solves in flight, under CapSkip's Max. Threads.
    private readonly SemaphoreSlim _gate = new(8);

    public async Task<string> SolveAsync(string sitekey, string url, CancellationToken ct)
    {
        await _gate.WaitAsync(ct);
        try { return (await Solver.RecaptchaAsync(sitekey, url, cancellationToken: ct)).Code; }
        finally { _gate.Release(); }
    }
}

// SignupTests.cs (only the first line changes)
// Classes in the same collection run one after another; other
// collections still run in parallel with them.
[Collection("solver")]
public class SignupTests(CapSkipFixture capskip)
{
    // ... the same tests ...
}

// SignupTests.cs (snippet: wrap the body of the test)
// When Timeout fires, the cancelled token makes the SDK throw: a
// TaskCanceledException while polling, CapSkip.NetworkException while
// submitting. Without this guard xUnit may report it as a second failure.
try
{
    var solved = await capskip.Solver.RecaptchaAsync(
        page.SiteKey, page.Url, cancellationToken: ct);
    // ... submit and assert ...
}
catch (Exception e) when (ct.IsCancellationRequested
                          && e is OperationCanceledException or CapSkipError)
{
    // The Timeout already failed this test with its own message.
}

# A hung run. MTP: add the extension once, then ask for a mini dump.
dotnet add package Microsoft.Testing.Extensions.HangDump
dotnet test --hangdump --hangdump-timeout 10m --hangdump-type Mini

# VSTest route: built in. The default dump type is Full (about 280 MB here).
# Do not use "none": the run ends but the hung test process stays alive.
dotnet test --blame-hang-timeout 10m --blame-hang-dump-type mini

// CapSkipFixture.Retry.cs
using CapSkip;

public sealed partial class CapSkipFixture
{
    // xUnit has no retry attribute. Retry only "could not solve" and give
    // up after `attempts`; every attempt takes its own place at the gate.
    public async Task<string> SolveWithRetryAsync(
        string sitekey, string url, CancellationToken ct, int attempts = 3)
    {
        for (var attempt = 1; ; attempt++)
        {
            try { return await SolveAsync(sitekey, url, ct); }
            catch (ApiException e) when (attempt < attempts
                                         && e.Message.Contains("UNSOLVABLE")) { }
        }
    }
}

// Unambiguous.cs
using CapSkip;
using TimeoutException = CapSkip.TimeoutException; // the alias picks CapSkip's

public class Unambiguous
{
    public async Task Solve(CapSkipClient solver, string sitekey, string url)
    {
        try { await solver.RecaptchaAsync(sitekey, url); }
        catch (TimeoutException) { }          // CapSkip.TimeoutException
        catch (System.TimeoutException) { }   // or the BCL one, spelled out
        catch (CapSkipError) { }              // or the base of all four
    }
}

// FakeApiTests.cs
using CapSkip;

// ApiClient is public and InAsync/ResAsync are virtual: swap it out and
// the solver never touches the network.
public sealed class FakeApi() : ApiClient("fake", 0)
{
    public override Task<string> InAsync(
        IDictionary<string, object?> options, CancellationToken cancellationToken = default) =>
        Task.FromResult("OK|1");

    public override Task<string> ResAsync(
        IDictionary<string, object?> query, CancellationToken cancellationToken = default) =>
        Task.FromResult("OK|fake-token");
}

public class FakeApiTests
{
    [Fact]
    public async Task Code_comes_from_the_fake()
    {
        var solver = new CapSkipClient { ApiClient = new FakeApi() };
        var solved = await solver.RecaptchaAsync("key", "https://example.test/",
            cancellationToken: TestContext.Current.CancellationToken);
        Assert.Equal("fake-token", solved.Code);
    }
}

# Command-line switches that matter for a solver suite (MTP mode).
dotnet test --max-threads 4                   # parallel test collections
dotnet test --parallel none                   # one test at a time
dotnet test --fail-skips on                   # CI: a skipped test fails
dotnet test --filter-method "*Signup_with*"   # one test, wildcard at the ends
dotnet test --output Detailed                 # show passing tests' output
dotnet test --timeout 20m                     # whole run; only cooperative
dotnet test --xunit-diagnostics on --diagnostic   # diagnostics to a .diag file
dotnet test --report-xunit-trx                # a .trx file for your CI

// SignupTests.cs: Steps 2 to 4 in one file
using System.Net;
using System.Net.Sockets;
using System.Text.RegularExpressions;
using CapSkip;

// One CapSkipFixture for the whole run, injected into every test class.
[assembly: AssemblyFixture(typeof(CapSkipFixture))]

public sealed partial class CapSkipFixture : IAsyncLifetime
{
    // The SDK never reads CAPSKIP_* itself, so read them here.
    private static string Env(string name, string fallback) =>
        Environment.GetEnvironmentVariable(name) ?? fallback;

    private readonly string _host = Env("CAPSKIP_HOST", "127.0.0.1");
    private readonly int _port = int.Parse(Env("CAPSKIP_PORT", "8080"));

    public CapSkipClient Solver { get; }
    public bool IsUp { get; private set; }
    public string SiteUrl { get; } = Env("STAGING_URL", "https://staging.example.com");

    public CapSkipFixture() => Solver = new CapSkipClient(
        apiKey: Env("CAPSKIP_API_KEY", "capskip"), host: _host, port: _port);

    // A TCP connect asks "is anything listening?" and sends no solve job.
    public async ValueTask InitializeAsync()
    {
        using var tcp = new TcpClient();
        using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(1));
        try
        {
            await tcp.ConnectAsync(_host, _port, timeout.Token);
            IsUp = true;
        }
        catch (Exception e) when (e is SocketException or OperationCanceledException) { }
    }

    public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}

public sealed record SignupPage(string Url, string SiteKey, string Csrf);

public sealed class SignupSite(string baseUrl) : IDisposable
{
    // One HttpClient per test: it keeps this test's cookies and no
    // other test's.
    private readonly HttpClient _http = new();

    public async Task<SignupPage> OpenAsync(CancellationToken ct)
    {
        var url = baseUrl + "/signup";
        var html = await _http.GetStringAsync(url, ct);
        return new SignupPage(url,
            Regex.Match(html, "data-sitekey=\"([^\"]+)\"").Groups[1].Value,
            Regex.Match(html, "name=\"csrfmiddlewaretoken\" value=\"([^\"]+)\"").Groups[1].Value);
    }

    public async Task<(HttpStatusCode Status, string Body)> SubmitAsync(
        SignupPage page, string token, CancellationToken ct)
    {
        using var request = new HttpRequestMessage(HttpMethod.Post, page.Url)
        {
            Content = new FormUrlEncodedContent(new Dictionary<string, string>
            {
                ["csrfmiddlewaretoken"] = page.Csrf,
                ["username"] = "ci-user",
                ["g-recaptcha-response"] = token,
            }),
        };
        request.Headers.Referrer = new Uri(page.Url); // HttpClient sends none
        using var response = await _http.SendAsync(request, ct);
        return (response.StatusCode, await response.Content.ReadAsStringAsync(ct));
    }

    public void Dispose() => _http.Dispose();
}

public class SignupTests(CapSkipFixture capskip)
{
    [Fact(Timeout = 120_000)] // milliseconds; also cancels the test's token
    public async Task Signup_with_a_solved_captcha_is_accepted()
    {
        Assert.SkipUnless(capskip.IsUp, "CapSkip is not running");
        var ct = TestContext.Current.CancellationToken;
        using var site = new SignupSite(capskip.SiteUrl);

        var page = await site.OpenAsync(ct);
        var solved = await capskip.Solver.RecaptchaAsync(
            page.SiteKey, page.Url, cancellationToken: ct);
        var (status, body) = await site.SubmitAsync(page, solved.Code, ct);

        Assert.Contains("welcome", body); // on failure xUnit prints the site's reason
        Assert.Equal(HttpStatusCode.OK, status);
    }
}