Reqnroll CAPTCHA in C#: Solve It From a Gherkin Step

To pass a CAPTCHA from a Reqnroll test, let a Gherkin step ask CapSkip for a token and put it into the form the scenario submits. This Reqnroll CAPTCHA guide is for the tester who has to get past a CAPTCHA on a site they are testing, not for adding one to their own pages. A BeforeScenario hook builds the CapSkip client, Reqnroll injects it into your step bindings, and the step that says the captcha is solved calls MtCaptchaAsync from the CapSkip NuGet package. CapSkip runs on your own Windows PC, so a long feature file adds no per-solve cost.
What you need
- CapSkip 4.3.0 or newer, because MTCaptcha solving arrived in that release, installed on a Windows PC. Installation and the first launch are in the setup guide.
- A .NET SDK. I ran everything on net10.0 and net8.0 (SDK 10.0.100, runtimes 10.0.0 and 8.0.27) with Reqnroll.xUnit 3.3.4, xunit 2.9.3 and CapSkip 1.7.0. A machine with only the 8 SDK is untested, and so is .NET Framework.
- A staging page you may automate, with an MTCaptcha widget whose sitekey sits in a script variable named mtcaptchaConfig.
- A way to reach CapSkip. In Local mode only the PC it runs on can call it, at 127.0.0.1. Server mode opens the API to your network or a public IP, which a separate test machine needs. You switch between them in the connection settings.
Nothing below touched the real CapSkip app or a real site. A mock of mine plays the CapSkip API and a sign-up page, and the genuine Reqnroll and CapSkip package run against it. Solve times and accept rules come from the mock itself, and every number is tagged with its setup.
Step 1: create the project
The xunit template pins xunit 2.9.3, the v2 line that Reqnroll.xUnit builds on, so add the two packages to it. A plain dotnet test worked with no global.json. Reqnroll finds feature files anywhere in the project, and each block below starts with the path to save it under.
# 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
Step 2: write the scenarios
The scenarios say what happens, not how, so a Reqnroll CAPTCHA step reads like any other. The captcha is solved inside a When step of every scenario, because a token works once. According to MTCaptcha, in its validate token guide, a token is checked once by default. The last scenario submits twice on purpose, and its expected text comes from my mock, so change the quoted words to what your site shows.
# 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"A second feature file reuses every step, which matters for the parallel runs below.
# 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"Step 3: a helper for your staging page
The next class is your own glue code, not part of CapSkip. It reads the sitekey and action from the page’s mtcaptchaConfig with two regexes, so adjust them to your markup. The helper sends the token in the mtcaptcha-verifiedtoken field with a Referer set by hand, because HttpClient sends none on a form submission.
Reqnroll builds one StagingSite per scenario, so cookies never leak between scenarios, and because the class is IDisposable Reqnroll disposes it afterwards: four scenarios gave four Dispose calls.
// 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();
}Step 4: build the client in a BeforeScenario hook
A hook class is a binding like any other, so its constructor can ask for the IObjectContainer of Reqnroll. The hook builds a CapSkipClient and registers that instance, and every binding that asks for a CapSkipClient gets it. The SDK never reads CAPSKIP_ variables itself, so the hook does. The SDK shares one HttpClient inside, so a client per scenario is cheap.
The hook also checks that something listens, with a TCP connect that sends no solve job. The Reqnroll hooks page says an exception in a BeforeScenario hook skips the steps. With the mock stopped, every scenario failed with the hook message and each step read skipped because of previous errors. The block sets an explicit Order, as that page recommends.
// 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));
}
}Leave the registration out and Reqnroll does not fall back to a default client: every scenario failed with Primitive types or structs cannot be resolved: System.String, with the path from SignupSteps to CapSkipClient.
Step 5: the step bindings for a Reqnroll CAPTCHA
Reqnroll creates a binding class once per scenario and fills its constructor, so fields hold state between that scenario’s steps. The Reqnroll context injection docs say injected objects live for one scenario. SignupSteps asks for the client, a StagingSite that Reqnroll builds itself, the ScenarioContext and an ITestOutputHelper, which the generated test class registers. It prints how long the solve took, shown at detailed verbosity.
The Then steps live in a second class that cannot see these fields, so the submit step leaves the reply in ScenarioContext, a dictionary shared by the scenario’s bindings. A missing key fails at run time with a KeyNotFoundException. For more than one value, a small class that both bindings ask for is safer.
I used MtCaptchaAsync rather than RecaptchaAsync. MTCaptcha needs no browser on your side: CapSkip reads the challenge text itself, and the SDK gives it the 120 second defaultTimeout, one number to reason about. The call sends the action the page declares, and per the SDK changelog an empty option is not sent. The API docs list the other options.
// 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"));
}Every step that awaits returns Task. An async void step is a trap: Reqnroll reports that async void methods are not supported and then fails every scenario in the project, including those that never use it. All four scenarios of the project in this guide failed that way once I added one unused async void method. The Reqnroll asynchronous bindings docs show async Task and also allows ValueTask.
Step 6: a transformation for the time limit
The step that says within 30 seconds takes a TimeSpan. With no transformation and the regex in SignupSteps, the scenario failed with an InvalidCastException: Invalid cast from System.String to System.TimeSpan. A StepArgumentTransformation supplies the missing conversion, and any later step that takes a duration can reuse it. Capturing only the digits looks like a shortcut but is worse: the step then ran with no error and received a TimeSpan of 30 days. The regex in SignupSteps captures the digits and the unit together, so the transformation receives the text 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);
}Step 7: run it
Put the settings into PowerShell environment variables, then start the suite from the project folder. The block shows the defaults; my runs set the port to 12740 on the mock and STAGING_URL to its address. For a real run, leave the first two out and set STAGING_URL to your page. Four scenarios passed on net10.0, and again on net8.0 after I changed TargetFramework in the project file.
# 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"
What Reqnroll generates for async steps
On build, Reqnroll turns each feature file into a C# class. In 3.3.4 the generated file sits next to the feature, as Features\Signup.feature.cs. Each feature is one test class implementing IAsyncLifetime, a plain scenario is a SkippableFact and an outline is a SkippableTheory with one InlineData row per example.
Every step is an awaited call such as await testRunner.GivenAsync with the step text, and every generated method returns Task.
Put a time limit on the solve
xUnit 2.9.3 gives a test no cancellation token, so the within step makes its own, and the SDK has its own limit, defaultTimeout. The table is from the mock on net10.0. The clock starts just before MtCaptchaAsync and stops in the catch block, except in the last row, which is the Reqnroll timer for the step.
| What the mock did | Time limit | What the step reported | Time |
|---|---|---|---|
| Never produced a token | 3 second step budget | No token within the step’s budget | 3004 ms |
| Never produced a token | 1 second step budget | The same message | 1014 ms |
| Held in.php for 10 seconds | 2 second step budget | The same message | 2012 ms |
| Never produced a token | None, client built with defaultTimeout 5 | No token before the SDK’s own deadline: timeout 5 exceeded | 7.8 s |
The first three rows end at the budget because the token reaches MtCaptchaAsync. Cancelling during polling raises a TaskCanceledException and cancelling during the submit a CapSkip NetworkException, so the step tests the token, not the type. The last row ends about three seconds late, because the SDK checks its deadline only when the next poll is due. I built that client with a defaultTimeout of 5 for that row only; the Step 4 block keeps the default 120.
The CapSkip TimeoutException shares a name with System.TimeoutException, and a test project imports System through implicit usings. A bare catch for TimeoutException next to using CapSkip fails with CS0104, an ambiguous reference. The alias in SignupSteps picks the CapSkip class, and writing CapSkip.TimeoutException or catching CapSkipError works too.
Run scenarios in parallel without flooding CapSkip
xUnit runs test classes side by side and the tests inside one class one after another. Reqnroll makes one class per feature file, so the feature file is your unit of parallelism. I moved Signup.feature and Login.feature out of the project and made four copies of Login.feature, each with its own Feature title (Login 1 to Login 4) and a second scenario. Copies that share a title build the same class and fail with CS0579, a duplicate GeneratedCodeAttribute. Every solve was held for 3 seconds in the mock. Total time is the dotnet test line, which includes start-up, and the last column is the most solves open at once. The first row ran on net10.0 and net8.0 with the same result, the others once on net10.0.
| Setup | Total time | Solves at once |
|---|---|---|
| Four feature files, xUnit defaults | 8.2 s | 4 |
| The same, maxParallelThreads 2 | 16.1 s | 2 |
| The same, maxParallelThreads 1 | 31.5 s | 1 |
| The same, parallelizeTestCollections false | 31.4 s | 1 |
| One feature file, one outline with 8 examples | 31.4 s | 1 |
One long feature file never overlaps its own scenarios, however many examples it has. To cap the solves, put a number in xunit.runner.json and copy the file to the build output. If your CapSkip version shows a Max. Threads setting for MTCaptcha, keep the number of parallel features at or under it. I did not look for one.
{
"$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>
I ran the default xUnit mode only. The generated assembly code defines a collection named ReqnrollNonParallelizableFeatures, but tagging my four features with @nonparallelizable only added an xUnit trait to the generated class and still gave 4 solves at once, so I do not rely on that tag.
Reaching CapSkip from another machine
Nothing forces the tests onto the solver’s PC. With CapSkip in Server mode, point CAPSKIP_HOST and CAPSKIP_PORT at it and the scenarios stay as they are. For my check the mock accepted connections on every interface, CAPSKIP_HOST held a non-loopback address of this PC, and four scenarios passed. With the mock on loopback only, that setting made every scenario fail with the hook message, so the address was really used. No second machine was involved. The setup guide says Server mode requires CapSkip to run as administrator, so start it that way on the server machine.
The SDK talks to CapSkip over plain HTTP, so anyone on the path can read the API key. Keep that hop off the open internet: a private network or a VPN, with API key validation switched on in CapSkip. Starting Server mode makes CapSkip open its port to every address, so to limit access to the machines you expect, add a Windows Firewall block rule for the rest. The solver stays on your own Windows hardware, and nothing is billed per solve. A static IP keeps the address stable.
Common errors with Reqnroll CAPTCHA tests
| What you see | Cause | Fix |
|---|---|---|
| CapSkip is not listening on the host and port | The TCP check in the hook found nothing there | Start CapSkip, check the connection settings and CAPSKIP_HOST |
| Primitive types or structs cannot be resolved: System.String | No CapSkipClient was registered before a step asked for one | Register it in the BeforeScenario hook |
| Every scenario fails with async void methods are not supported | One binding method is async void | Return Task |
| InvalidCastException from String to TimeSpan | No transformation for the duration text. A digits-only capture would give 30 days instead | Add the StepArgumentTransformation and capture digits and unit together |
| CS0104 on TimeoutException | System and CapSkip both define it | Alias the CapSkip class, or catch CapSkipError |
| KeyNotFoundException in a Then step | The ScenarioContext key was never set or is misspelled | Check both spellings, or inject a small shared class |
| The site says the token was already used | One token was submitted twice | Solve again in the scenario before every submission |
Other codes a solve can raise are listed in the API docs.
FAQ
Can I use RecaptchaAsync in a Reqnroll step instead?
Yes, in principle. The hook, the injection, the time limit and the parallel settings do not change. The solve call, the form field (g-recaptcha-response) and the timeout (recaptchaTimeout) do. I ran only MtCaptchaAsync.
Will a cloud-hosted build agent work?
Yes, through Server mode. On a hosted agent 127.0.0.1 is the agent itself, so CapSkip has to run on a Windows machine of yours that the agent can reach over the network. Set CAPSKIP_HOST to that machine and store the API key as a CI secret. A hosted agent was beyond what I ran.
The short version
For a Reqnroll CAPTCHA step, build the CapSkip client in a BeforeScenario hook and register it. Solve inside a When step, once per scenario, with a time limit the step enforces. Return Task from every binding, add a transformation for durations, and treat feature files as your parallel unit. Other .NET CAPTCHA types are on the C# CAPTCHA solver page, and the product itself is on the MTCaptcha solver page.
A BDD suite repeats scenarios for every page and release, and a per-solve price makes each run cost money. Running an unlimited captcha solver on your own Windows machine keeps the price of a nightly run flat.
