Капча в Reqnroll на C#: решение из шага Gherkin

Чтобы пройти капчу из теста Reqnroll, пусть шаг Gherkin запросит у CapSkip токен и подставит его в форму, которую отправляет сценарий. Это руководство по Reqnroll и капче предназначено для тестировщика, которому нужно пройти капчу на тестируемом сайте, а не для добавления капчи на собственные страницы. Хук BeforeScenario создаёт клиент CapSkip, Reqnroll внедряет его в привязки шагов, а шаг, в котором сказано, что капча решена, вызывает MtCaptchaAsync из NuGet-пакета CapSkip. CapSkip работает на вашем ПК с Windows, поэтому длинный feature-файл не добавляет платы за каждое решение.
Что понадобится
- CapSkip 4.3.0 или новее, потому что решение MTCaptcha появилось в этом релизе, установленный на ПК с Windows. Установка и первый запуск описаны здесь: руководство по настройке.
- Нужен .NET SDK. Я запускал всё на net10.0 и net8.0 (SDK 10.0.100, рантаймы 10.0.0 и 8.0.27) с Reqnroll.xUnit 3.3.4, xunit 2.9.3 и CapSkip 1.7.0. Машина только с SDK 8 не проверялась, как и .NET Framework.
- Staging-страница, которую вам можно автоматизировать, с виджетом MTCaptcha, чей sitekey лежит в переменной скрипта mtcaptchaConfig.
- Способ достучаться до CapSkip. В Local mode его может вызвать только ПК, на котором он запущен, по адресу 127.0.0.1. Server mode открывает API для вашей сети или публичного IP, что нужно отдельной тестовой машине. Переключаются они здесь: Настройки подключения.
Ничто из описанного ниже не затрагивало настоящее приложение CapSkip или настоящий сайт. Моя имитация изображает API CapSkip и страницу регистрации, а настоящие Reqnroll и пакет CapSkip работают с ней. Время решения и правила приёма задаёт сама имитация, и каждое число помечено своей конфигурацией.
Шаг 1: создаём проект
Шаблон xunit фиксирует xunit 2.9.3, линию v2, на которой собран Reqnroll.xUnit, поэтому добавьте в него два пакета. Обычный dotnet test сработал без global.json. Reqnroll находит feature-файлы в любом месте проекта, а каждый блок ниже начинается с пути, по которому его нужно сохранить.
# PowerShell dotnet new xunit -n CapSkipBdd -f net10.0 cd CapSkipBdd rm UnitTest1.cs # the template's sample test; delete it dotnet add package Reqnroll.xUnit dotnet add package CapSkip mkdir Features, Hooks, Steps, Support
Шаг 2: напишите сценарии
Сценарии описывают, что происходит, а не как, поэтому шаг Reqnroll с капчей читается как любой другой. Капча решается внутри шага When в каждом сценарии, потому что токен работает один раз. По данным MTCaptcha, из руководства по проверке токенаследует, что по умолчанию токен проверяется один раз. Последний сценарий намеренно отправляет форму дважды, а ожидаемый текст берётся из моей имитации, поэтому замените слова в кавычках на то, что показывает ваш сайт.
# Features/Signup.feature
Feature: Sign-up behind a CAPTCHA
A visitor can only sign up with a token that CapSkip solved just now.
Scenario Outline: A solved CAPTCHA is accepted on each page
Given the "<path>" page is open
When the captcha is solved
And the form is submitted
Then the site says "Welcome aboard"
Examples:
| path |
| /signup |
| /signup?plan=pro |
Scenario: A token works once
Given the "/signup" page is open
When the captcha is solved within 30 seconds
And the form is submitted
And the form is submitted
Then the site says "token already used"Второй feature-файл повторно использует все шаги, что важно для параллельных запусков ниже.
# Features/Login.feature
Feature: Login behind a CAPTCHA
The step bindings are shared, so a second feature file costs no new code.
Scenario: A solved CAPTCHA signs the user in
Given the "/login" page is open
When the captcha is solved
And the form is submitted
Then the site says "Welcome aboard"Шаг 3: вспомогательный класс для вашей staging-страницы
Следующий класс является вашим собственным связующим кодом и не входит в CapSkip. Он читает sitekey и action из mtcaptchaConfig страницы двумя регулярными выражениями, так что подстройте их под свою разметку. Вспомогательный класс отправляет токен в поле mtcaptcha-verifiedtoken с вручную заданным Referer, потому что HttpClient при отправке формы его не добавляет.
Reqnroll создаёт один StagingSite на сценарий, поэтому cookie не перетекают между сценариями, а раз класс реализует IDisposable, Reqnroll освобождает его после сценария: четыре сценария дали четыре вызова Dispose.
// Support/StagingSite.cs
using System.Net;
using System.Text.RegularExpressions;
namespace CapSkipBdd.Support;
public sealed record SignupPage(string Url, string SiteKey, string Action);
// Reqnroll builds one of these per scenario and disposes it afterwards,
// so each scenario has its own HttpClient and its own cookies.
public sealed class StagingSite : IDisposable
{
private readonly string _baseUrl =
Environment.GetEnvironmentVariable("STAGING_URL") ?? "https://staging.example.com";
private readonly HttpClient _http = new();
public async Task<SignupPage> OpenAsync(string path, CancellationToken ct)
{
var url = _baseUrl + path;
var html = await _http.GetStringAsync(url, ct);
// Adjust both patterns to how your page writes its mtcaptchaConfig.
var sitekey = Regex.Match(html, "\"sitekey\"\\s*:\\s*\"([^\"]+)\"").Groups[1].Value;
var action = Regex.Match(html, "\"action\"\\s*:\\s*\"([^\"]+)\"").Groups[1].Value;
return new SignupPage(url, sitekey, action);
}
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>
{
["user"] = "bdd-user",
["password"] = "YOUR_PASSWORD",
["mtcaptcha-verifiedtoken"] = 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();
}Шаг 4: создайте клиент в хуке BeforeScenario
Класс хука является такой же привязкой, как любая другая, поэтому его конструктор может запросить IObjectContainer из Reqnroll. Хук создаёт CapSkipClient и регистрирует этот экземпляр, а каждая привязка, которая запрашивает CapSkipClient, получает его. SDK сам никогда не читает переменные CAPSKIP_, поэтому их читает хук. Внутри SDK использует один общий HttpClient, так что клиент на сценарий обходится дёшево.
Хук также проверяет, что кто-то слушает порт, с помощью TCP-подключения, которое не отправляет задание на решение. В документации Reqnroll на странице о хуках сказано, что исключение в хуке BeforeScenario приводит к пропуску шагов. При остановленной имитации каждый сценарий падал с сообщением хука, а каждый шаг получал статус skipped because of previous errors. Блок задаёт явный Order, как рекомендует эта страница.
// Hooks/CapSkipHooks.cs
using System.Net.Sockets;
using CapSkip;
using Reqnroll;
using Reqnroll.BoDi;
namespace CapSkipBdd.Hooks;
[Binding]
public sealed class CapSkipHooks(IObjectContainer container)
{
// The SDK never reads CAPSKIP_* itself, so read them here.
private static string Env(string name, string fallback) =>
Environment.GetEnvironmentVariable(name) ?? fallback;
[BeforeScenario(Order = 0)]
public async Task BuildClient()
{
var host = Env("CAPSKIP_HOST", "127.0.0.1");
var port = int.Parse(Env("CAPSKIP_PORT", "8080"));
// A TCP connect asks "is anything listening?" and sends no solve job.
using var tcp = new TcpClient();
using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(1));
try { await tcp.ConnectAsync(host, port, timeout.Token); }
catch (Exception e) when (e is SocketException or OperationCanceledException)
{
throw new InvalidOperationException($"CapSkip is not listening on {host}:{port}");
}
// Every binding class that asks for a CapSkipClient now gets this one.
container.RegisterInstanceAs(new CapSkipClient(
apiKey: Env("CAPSKIP_API_KEY", "capskip"), host: host, port: port));
}
}Если убрать регистрацию, Reqnroll не подставляет клиент по умолчанию: каждый сценарий падал с ошибкой Primitive types or structs cannot be resolved: System.String и путём от SignupSteps до CapSkipClient.
Шаг 5: привязки шагов для капчи в Reqnroll
Reqnroll создаёт класс привязок один раз на сценарий и заполняет его конструктор, поэтому поля хранят состояние между шагами этого сценария. В документации Reqnroll по внедрению контекста сказано, что внедрённые объекты живут один сценарий. SignupSteps запрашивает клиент, StagingSite, который Reqnroll создаёт сам, ScenarioContext и ITestOutputHelper, который регистрирует сгенерированный тестовый класс. Он выводит время решения, видимое при уровне детализации detailed.
Шаги Then находятся во втором классе, который не видит эти поля, поэтому шаг отправки оставляет ответ в ScenarioContext, словаре, общем для привязок сценария. Отсутствующий ключ приводит к ошибке KeyNotFoundException во время выполнения. Если значений больше одного, надёжнее небольшой класс, который запрашивают обе привязки.
Я использовал MtCaptchaAsync, а не RecaptchaAsync. MTCaptcha не требует браузера на вашей стороне: CapSkip сам читает текст задачи, а SDK задаёт ему defaultTimeout в 120 секунд, то есть одно число, о котором нужно помнить. Вызов отправляет action, который объявляет страница, а по журналу изменений SDK пустой параметр не отправляется. Документация API перечисляет остальные параметры.
// Steps/SignupSteps.cs
using System.Diagnostics;
using CapSkip;
using CapSkipBdd.Support;
using Reqnroll;
using Xunit.Abstractions;
// System is imported too, and it has a TimeoutException of its own (CS0104).
using SolverTimeout = CapSkip.TimeoutException;
namespace CapSkipBdd.Steps;
// Reqnroll creates one of these per scenario and fills the constructor.
[Binding]
public sealed class SignupSteps(
CapSkipClient solver, StagingSite site, ScenarioContext scenario, ITestOutputHelper output)
{
private SignupPage? _page;
private string _token = "";
[Given("the {string} page is open")]
public async Task OpenPage(string path) =>
_page = await site.OpenAsync(path, CancellationToken.None);
[When("the captcha is solved")]
public async Task Solve() => await SolveWith(CancellationToken.None);
[When(@"the captcha is solved within (\d+ seconds)")]
public async Task SolveWithin(TimeSpan limit)
{
using var budget = new CancellationTokenSource(limit);
await SolveWith(budget.Token);
}
[When("the form is submitted")]
public async Task Submit()
{
var (status, body) = await site.SubmitAsync(_page!, _token, CancellationToken.None);
scenario["reply"] = $"{(int)status} {body}"; // the Then steps live in another class
}
private async Task SolveWith(CancellationToken ct)
{
// Pass the sitekey and action the page itself declares.
var options = new Dictionary<string, object?> { ["action"] = _page!.Action };
var clock = Stopwatch.StartNew();
try
{
var solved = await solver.MtCaptchaAsync(_page.SiteKey, _page.Url, options, ct);
_token = solved.Token!;
output.WriteLine($"solved in {clock.ElapsedMilliseconds} ms");
}
// A cancelled submit surfaces as a NetworkException and a cancelled poll as a
// TaskCanceledException, so test the token itself.
catch (Exception) when (ct.IsCancellationRequested)
{
Assert.Fail($"CapSkip gave no token within the step's budget ({clock.ElapsedMilliseconds} ms)");
}
catch (SolverTimeout e)
{
Assert.Fail($"CapSkip gave no token before the SDK's own deadline: {e.Message}");
}
}
}// Steps/ReplySteps.cs
using Reqnroll;
namespace CapSkipBdd.Steps;
[Binding]
public sealed class ReplySteps(ScenarioContext scenario)
{
[Then("the site says {string}")]
public void TheSiteSays(string text) =>
Assert.Contains(text, scenario.Get<string>("reply"));
}Каждый шаг, который что-то ожидает, возвращает Task. Шаг async void становится ловушкой: Reqnroll сообщает, что методы async void не поддерживаются, а затем роняет каждый сценарий в проекте, в том числе те, где он не используется. Все четыре сценария проекта из этого руководства упали именно так, когда я добавил один неиспользуемый метод async void. В документации Reqnroll по асинхронным привязкам показан async Task, а ValueTask тоже допускается.
Шаг 6: преобразование для лимита времени
Шаг, в котором сказано within 30 seconds, принимает TimeSpan. Без преобразования и с регулярным выражением из SignupSteps сценарий упал с InvalidCastException: Invalid cast from System.String to System.TimeSpan. StepArgumentTransformation даёт недостающее преобразование, и любой следующий шаг, принимающий длительность, может его использовать. Захват только цифр выглядит как короткий путь, но хуже: тогда шаг выполнялся без ошибки и получал TimeSpan в 30 дней. Регулярное выражение в SignupSteps захватывает цифры и единицу вместе, поэтому преобразование получает текст 30 seconds.
// Steps/Durations.cs
using Reqnroll;
namespace CapSkipBdd.Steps;
[Binding]
public sealed class Durations
{
// Without this, the TimeSpan parameter fails with an InvalidCastException.
[StepArgumentTransformation(@"(\d+) seconds")]
public TimeSpan InSeconds(int seconds) => TimeSpan.FromSeconds(seconds);
}Шаг 7: запустите
Задайте настройки в переменных окружения PowerShell, затем запустите набор тестов из папки проекта. Блок показывает значения по умолчанию; в моих запусках порт имитации был 12740, а STAGING_URL указывал на её адрес. Для настоящего запуска опустите первые два и задайте в STAGING_URL вашу страницу. Четыре сценария прошли на net10.0, а потом и на net8.0 после того, как я изменил TargetFramework в файле проекта.
# PowerShell. The hook and the helper read these; unset ones fall back to 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 --logger "console;verbosity=detailed"
Что Reqnroll генерирует для асинхронных шагов
При сборке Reqnroll превращает каждый feature-файл в класс C#. В 3.3.4 сгенерированный файл лежит рядом с feature-файлом, как Features\Signup.feature.cs. Каждая фича становится одним тестовым классом, реализующим IAsyncLifetime, обычный сценарий превращается в SkippableFact, а структура сценария (outline) в SkippableTheory с одной строкой InlineData на каждый пример.
Каждый шаг представляет собой ожидаемый вызов, например await testRunner.GivenAsync с текстом шага, и каждый сгенерированный метод возвращает Task.
Ограничьте время решения
xUnit 2.9.3 не передаёт тесту токен отмены, поэтому шаг within создаёт свой собственный, а у SDK есть свой лимит, defaultTimeout. Таблица получена на имитации на net10.0. Отсчёт начинается прямо перед MtCaptchaAsync и останавливается в блоке catch, кроме последней строки, где указан таймер Reqnroll для шага.
| Что сделала имитация | Лимит времени | Что сообщил шаг | Время |
|---|---|---|---|
| Токен так и не выдан | Бюджет шага 3 секунды | Токен не получен в пределах бюджета шага | 3004 ms |
| Токен так и не выдан | Бюджет шага 1 секунда | То же сообщение | 1014 ms |
| Держала in.php 10 секунд | Бюджет шага 2 секунды | То же сообщение | 2012 ms |
| Токен так и не выдан | Нет, клиент создан с defaultTimeout 5 | Токен не получен до собственного дедлайна SDK: timeout 5 exceeded | 7.8 s |
Первые три строки заканчиваются на границе бюджета, потому что токен отмены доходит до MtCaptchaAsync. Отмена во время опроса вызывает TaskCanceledException, а отмена во время отправки вызывает CapSkip NetworkException, поэтому шаг проверяет токен отмены, а не тип исключения. Последняя строка заканчивается примерно на три секунды позже, потому что SDK проверяет свой дедлайн, только когда подходит время следующего опроса. Этот клиент я создал с defaultTimeout 5 только для этой строки; блок Шага 4 оставляет значение по умолчанию 120.
CapSkip TimeoutException имеет то же имя, что и System.TimeoutException, а тестовый проект импортирует System через неявные using. Простой catch для TimeoutException рядом с using CapSkip падает с CS0104, неоднозначной ссылкой. Псевдоним в SignupSteps выбирает класс CapSkip, а запись CapSkip.TimeoutException или перехват CapSkipError тоже работает.
Запускайте сценарии параллельно, не заваливая CapSkip
xUnit запускает тестовые классы одновременно, а тесты внутри одного класса по очереди. Reqnroll делает один класс на feature-файл, поэтому единицей параллелизма служит feature-файл. Я вынес Signup.feature и Login.feature из проекта и сделал четыре копии Login.feature, каждую со своим заголовком Feature (от Login 1 до Login 4) и вторым сценарием. Копии с одинаковым заголовком создают один и тот же класс и падают с CS0579, дублирующимся GeneratedCodeAttribute. Каждое решение в имитации удерживалось 3 секунды. Общее время взято из строки dotnet test, она включает запуск, а последний столбец показывает наибольшее число одновременно открытых решений. Первая строка выполнялась на net10.0 и net8.0 с одним результатом, остальные по одному разу на net10.0.
| Настройка | Общее время | Решений одновременно |
|---|---|---|
| Четыре feature-файла, настройки xUnit по умолчанию | 8.2 s | 4 |
| То же, maxParallelThreads 2 | 16.1 s | 2 |
| То же, maxParallelThreads 1 | 31.5 s | 1 |
| То же, parallelizeTestCollections false | 31.4 s | 1 |
| Один feature-файл, одна структура сценария с 8 примерами | 31.4 s | 1 |
Один длинный feature-файл никогда не пересекает собственные сценарии, сколько бы в нём ни было примеров. Чтобы ограничить число решений, задайте число в xunit.runner.json и скопируйте файл в выходную папку сборки. Если в вашей версии CapSkip есть настройка Max. Threads для MTCaptcha, держите число параллельных фич не выше неё. Я такую не искал.
{
"$schema": "https://xunit.net/schema/current/xunit.runner.schema.json",
"maxParallelThreads": 2
}<!-- CapSkipBdd.csproj: add inside the Project element --> <ItemGroup> <Content Include="xunit.runner.json" CopyToOutputDirectory="PreserveNewest" /> </ItemGroup>
Я запускал только режим xUnit по умолчанию. Сгенерированный код сборки определяет коллекцию ReqnrollNonParallelizableFeatures, но пометка моих четырёх фич тегом @nonparallelizable лишь добавила трейт xUnit в сгенерированный класс и всё равно давала 4 одновременных решения, поэтому я на этот тег не полагаюсь.
Доступ к CapSkip с другой машины
Ничто не обязывает запускать тесты на ПК с решателем. Если CapSkip работает в Server mode, направьте на него CAPSKIP_HOST и CAPSKIP_PORT, и сценарии останутся прежними. В моей проверке имитация принимала подключения на всех интерфейсах, CAPSKIP_HOST содержал не loopback-адрес этого ПК, и четыре сценария прошли. Когда имитация слушала только loopback, та же настройка роняла каждый сценарий с сообщением хука, так что адрес действительно использовался. Второй машины в проверке не было. В руководстве по настройке сказано, что Server mode требует запуска CapSkip от имени администратора, поэтому запускайте его так на серверной машине.
SDK обращается к CapSkip по обычному HTTP, поэтому любой на пути может прочитать API-ключ. Не выпускайте этот участок в открытый интернет: используйте частную сеть или VPN и включите в CapSkip проверку API-ключа. Запуск Server mode открывает порт CapSkip для всех адресов, поэтому, чтобы ограничить доступ ожидаемыми машинами, добавьте для остальных блокирующее правило брандмауэра Windows. Решатель остаётся на вашем собственном оборудовании с Windows, и плата за каждое решение не взимается. Статический IP сохраняет адрес стабильным.
Частые ошибки в тестах Reqnroll с капчей
| Что вы видите | Причина | Исправить |
|---|---|---|
| CapSkip не слушает на этом хосте и порту | TCP-проверка в хуке ничего там не нашла | Запустите CapSkip, проверьте Настройки подключения и CAPSKIP_HOST |
| Primitive types or structs cannot be resolved: System.String | CapSkipClient не был зарегистрирован до того, как шаг его запросил | Зарегистрируйте его в хуке BeforeScenario |
| Каждый сценарий падает с async void methods are not supported | Один метод привязки объявлен как async void | Возвращайте Task |
| InvalidCastException из String в TimeSpan | Нет преобразования для текста длительности. Захват одних цифр дал бы вместо этого 30 дней | Добавьте StepArgumentTransformation и захватывайте цифры и единицу вместе |
| CS0104 на TimeoutException | Его определяют и System, и CapSkip | Задайте псевдоним для класса CapSkip или перехватывайте CapSkipError |
| KeyNotFoundException в шаге Then | Ключ ScenarioContext не задан или написан с ошибкой | Проверьте оба написания или внедрите небольшой общий класс |
| Сайт сообщает, что токен уже использован | Один токен отправлен дважды | Решайте капчу заново в сценарии перед каждой отправкой |
Другие коды, которые может вызвать решение, смотрите здесь: Документация API.
FAQ
Можно ли вместо этого использовать RecaptchaAsync в шаге Reqnroll?
Да, в принципе. Хук, внедрение, лимит времени и параметры параллелизма не меняются. Меняются вызов решения, поле формы (g-recaptcha-response) и тайм-аут (recaptchaTimeout). Я запускал только MtCaptchaAsync.
Подойдёт ли облачный агент сборки?
Да, через Server mode. На облачном агенте 127.0.0.1 это сам агент, поэтому CapSkip должен работать на вашей машине с Windows, до которой агент достаёт по сети. Укажите в CAPSKIP_HOST эту машину и храните API-ключ как секрет CI. Облачный агент выходил за рамки того, что я запускал.
Коротко
Для шага Reqnroll с капчей создайте клиент CapSkip в хуке BeforeScenario и зарегистрируйте его. Решайте капчу в шаге When один раз на сценарий, с лимитом времени, который обеспечивает шаг. Возвращайте Task из каждой привязки, добавьте преобразование для длительностей и считайте единицей параллелизма feature-файлы. Другие типы капчи для .NET описаны на странице сервиса распознавания капчи для C#, а сам продукт описан на странице решения MTCaptcha.
BDD-набор повторяет сценарии для каждой страницы и релиза, а цена за каждое решение делает каждый прогон платным. Когда безлимитный сервис распознавания капчи работает на вашем компьютере с Windows, цена ночного прогона остаётся неизменной.
