Test PolyBot Handlers with RunTest and UpdateMocker

PolyBot’s test harness lets you exercise your handler code in complete isolation — no bot token, no Telegram servers, no real HTTP. PolyBotClient.RunTest() builds the service provider, swaps in an in-memory PolyTests client, and returns an UpdateMocker that pushes synthetic updates directly into the generated router.

RunTest

Call RunTest(CancellationToken cancellationToken = default) instead of RunPollingAsync(). The method:

Builds the service provider the same way as polling, but skips the bot-token requirement
Resolves the IUpdateHandler (your generated BotRouter)
Registers PolyTests as ITelegramBotClient — fully offline, no network calls
Returns an UpdateMocker bound to that provider and handler

PolyBotClient client = new PolyBotClient();
client.Services.AddPolyBotRouter();
// Register your own services as usual
client.Services.AddSingleton<IMyService, MyService>();

UpdateMocker mock = client.RunTest();

BotClient becomes accessible on the PolyBotClient after RunTest() is called, just like after RunPollingAsync(). Accessing it before either method is called throws InvalidOperationException.

UpdateMocker

UpdateMocker is the test controller returned by RunTest(). It exposes:

Member	Type	Description
`Services`	`IServiceProvider`	The built service provider — resolve services for assertions.
`BotClient`	`PolyTests`	The in-memory bot client. Use `SentRequests` to assert outgoing API calls.
`Update(Update update, CancellationToken cancellationToken = default)`	`Task<Update>`	Pushes any raw `Update` through the router; auto-assigns `Id` if zero.
`Message(string text, long userId = 42, long chatId = 1, CancellationToken cancellationToken = default)`	`Task<Update>`	Pushes a plain text message with auto-incremented `Message.Id`.
`Command(string command, long userId = 42, long chatId = 1, CancellationToken cancellationToken = default)`	`Task<Update>`	Pushes a bot-command message; the leading `/` is optional and added automatically.
`Callback(string data, long userId = 42, CancellationToken cancellationToken = default)`	`Task<Update>`	Pushes a callback query with the given `Data` string.
`InlineQuery(string query, long userId = 42, CancellationToken cancellationToken = default)`	`Task<Update>`	Pushes an inline query with the given `Query` string.

Default IDs

All helper methods default to userId = 42 and chatId = 1 (where applicable), so you only specify them when your test exercises multi-user or multi-chat logic:

await mock.Message("hello");                      // userId=42, chatId=1
await mock.Message("hello", userId: 99);          // userId=99, chatId=1
await mock.Message("hello", userId: 10, chatId: 20);

Return value

Every method returns the Update that was routed, with its auto-assigned IDs populated. This lets you write deterministic assertions about the update sequence:

Update first  = await mock.Message("one");
Update second = await mock.Message("two");

Assert.IsTrue(first.Id < second.Id);   // IDs are monotonically increasing

Asserting outgoing API calls

mock.BotClient.SentRequests is an IReadOnlyList<object> of every request the handler sent through ITelegramBotClient, in order. Filter by request type to assert specific calls:

IReadOnlyList<object> sent = mock.BotClient.SentRequests;

// Assert a SendMessage was sent
SendMessageRequest? reply = sent.OfType<SendMessageRequest>().FirstOrDefault();
Assert.IsNotNull(reply);
Assert.AreEqual("Hello!", reply.Text);

// Assert a callback query was answered
Assert.IsTrue(sent.OfType<AnswerCallbackQueryRequest>().Any());

Complete test example

This example covers a message handler, a /start command, and a callback query — reading configuration from a JSON file and asserting all three outgoing requests:

[TestMethod]
public async Task Bot_HandlesMessageCommandAndCallback()
{
    // Write a minimal config file with a bot token (ignored in test mode)
    string configPath = Path.GetTempFileName() + ".json";
    File.WriteAllText(configPath, """
        { "PolyBot": { "BotToken": "1:test", "BotUsername": "mybot" } }
        """);

    try
    {
        await using PolyBotClient client = new PolyBotClient();
        client.Configuration.AddJsonFile(configPath);
        client.Services.AddSingleton<IGreetingService, GreetingService>();
        client.Services.AddPolyBotRouter();

        UpdateMocker mock = client.RunTest();

        // Plain text message
        Update msgUpdate = await mock.Message("hello world", userId: 100);
        Assert.IsTrue(msgUpdate.Id > 0);

        // Bot command — leading slash is optional
        Update cmdUpdate = await mock.Command("start", userId: 200);
        Assert.IsTrue(cmdUpdate.Id > msgUpdate.Id); // monotonically increasing

        // Callback query
        Update cbUpdate = await mock.Callback("item:42:open", userId: 300);

        // Inline query
        await mock.InlineQuery("search term", userId: 400);

        // Assert outgoing API calls
        IReadOnlyList<object> sent = mock.BotClient.SentRequests;

        Assert.IsTrue(
            sent.OfType<SendMessageRequest>().Any(r => r.Text.Contains("hello")),
            "Echo handler should have replied to the plain message");

        Assert.IsTrue(
            sent.OfType<SendMessageRequest>().Any(r => r.Text.StartsWith("Welcome")),
            "/start handler should have sent a welcome message");

        Assert.IsTrue(
            sent.OfType<AnswerCallbackQueryRequest>().Any(),
            "Callback handler should have answered the callback query");
    }
    finally
    {
        File.Delete(configPath);
    }
}

Pushing arbitrary updates

For update types that don’t have a dedicated helper method, use mock.Update(new Update { ... }) directly. The Id is auto-assigned when it is zero:

Update pollUpdate = await mock.Update(new Update
{
    Poll = new Poll
    {
        Id = "poll-1",
        Question = "Favourite colour?",
        Options = [],
        TotalVoterCount = 0,
        IsClosed = false,
        IsAnonymous = true,
        Type = PollType.Regular,
    },
});

Assert.IsTrue(pollUpdate.Id > 0);

Configuration binding in test mode

PolyBotClient binds Configuration exactly the same way in test mode as it does for polling. You can attach a JSON file, environment variables, or in-memory values:

JSON file
In-memory
Constructor override

client.Configuration.AddJsonFile("appsettings.Test.json");

client.Configuration.AddInMemoryCollection(new Dictionary<string, string?>
{
    ["PolyBot:BotUsername"] = "testbot",
});

PolyBotClient client = new PolyBotClient(
    new PolyBotOptions { BotUsername = "testbot" });

BotToken is not required in test mode — PolyBotClient detects a missing token and silently swaps in PolyTests. You only need a token when calling RunPollingAsync.

Get Started

Core Concepts

Features

Hosting & Deployment

Testing

Test PolyBot Handlers with RunTest and UpdateMocker

RunTest

UpdateMocker

Default IDs

Return value

Asserting outgoing API calls

Complete test example

Pushing arbitrary updates

Configuration binding in test mode

​RunTest

​UpdateMocker

​Default IDs

​Return value

​Asserting outgoing API calls

​Complete test example

​Pushing arbitrary updates

​Configuration binding in test mode

RunTest

UpdateMocker

Default IDs

Return value

Asserting outgoing API calls

Complete test example

Pushing arbitrary updates

Configuration binding in test mode