Forem: Stepan Romankov

Your AI Should Be Writing Tests. The Unfair Advantage Every Vibe Coder Ignores.

Stepan Romankov — Mon, 02 Mar 2026 20:28:25 +0000

A test is a note you leave for the computer. It says: "this thing works like this, and if it ever stops working like this, let me know."

That's it. Imagine you built a calculator. You write a note that says "2 + 3 must equal 5." The computer checks this note every time something changes. If your calculator suddenly returns 6, the note fires. You don't need to understand how the calculator works internally. You just know it's broken because 2 + 3 is not 6.

This is the entire concept.

What a test looks like in practice

Before any code, here's the plain-English version:

I have a function called calculatePrice. I give it an item that costs $10 and a quantity of 3. I expect $30 back. If I get anything else, something is wrong.

In Go, that becomes:

func TestCalculatePrice(t *testing.T) {
    got := calculatePrice(10, 3)
    if got != 30 {
        t.Errorf("expected 30, got %d", got)
    }
}

Seven lines. The machine runs this, checks the result, and tells you if it's wrong. You can have hundreds of these notes scattered across your project. They run in seconds.

That's a unit test. "Unit" because it tests one small unit of behavior. Not the whole app. Not the database. Just: does this function do the one thing it's supposed to.

Why this matters if you vibe code

Here's the scenario. You're building an online store. It has a price calculation function. It works. Users are buying things. Life is good.

You open ChatGPT or Claude and say: "Add a 10% discount for orders over $100."

The AI gives you 40 lines of code. It looks right. The discount logic is there. You paste it in, try a $150 order, see a $135 total. Ship it.

What you didn't notice: the AI rewrote calculatePrice to handle the discount, and in the process it changed how tax is applied. Orders under $100 now have tax calculated twice. Your $10 item costs $10.80 instead of $10.50. Nobody tells you this because you're not going to manually test every old scenario after every change.

A test would have caught it instantly:

--- FAIL: TestCalculatePrice
    expected 1050 (cents), got 1080

This is not a hypothetical. Large language models hallucinate. They confidently produce code that compiles, looks reasonable, and is subtly wrong. They'll rename a variable and forget to update one reference. They'll change what a function gives back and break something three files away. They'll "simplify" a condition and break a rare scenario. The confidence is the dangerous part. The code doesn't look broken. It just is.

Tests don't care who wrote the code

A test doesn't know if a human or an AI wrote the function it's checking. It doesn't care. It just runs the function, compares the output to what you said it should be, and passes or fails.

This makes tests the perfect safety net for vibe coding. You can let the AI rewrite entire files. You can tell it to refactor, restructure, change the architecture. As long as the tests pass, the behavior you care about is intact. The moment something breaks, you'll know immediately, not three weeks later when a user reports a weird charge on their credit card.

There's a catch though.

Tests that spy on implementation are useless

There are two ways to write a test. One is good. One will ruin your life.

Good: "I give the function these inputs, I expect this output."

Bad: "The function must call database.Save() exactly once, then call cache.Invalidate() with the argument "users", then return a struct with field processedAt set to the current timestamp."

The second kind tests HOW the code works internally. This seems thorough. It's actually a trap. The moment the AI (or you, or a coworker) rewrites the internals, every single one of those tests breaks, even if the behavior is perfectly correct. You moved some code into a separate place? Tests fail. You switched from one internal library to another? Tests fail. The function still does exactly what it's supposed to, but the tests don't know that because they were watching the gears, not the output.

For vibe coding this is fatal. The AI rewrites internals on every prompt. If your tests check implementation details, they'll break every single time you ask the AI to change anything. You'll spend more time fixing tests than writing features. Eventually you'll start ignoring failing tests, and then you have no tests at all.

Write tests that check behavior. Input in, expected output out. The internals are the AI's problem. The behavior is your contract with reality.

A practical rule: if you can describe what a test checks without mentioning names of internal code parts or step-by-step details, it's a behavioral test. "An order with three items at $10 each costs $30." That sentence says nothing about implementation. Any code that makes it true is correct code.

How many tests do you need

I'm honestly not sure there's a universal answer here. The standard advice is "test everything," but I think for vibe coding the priority is different. Test the things that would hurt if they broke silently. Price calculations. Authentication. Data that gets saved to a database. The core stuff.

If the AI generates some utility code that formats a date for display, maybe you don't need a test for that. If it breaks, you'll see it on screen. But if it generates code that decides whether a user gets charged $50 or $500? Yeah, write a test.

Start small. Five tests that cover the most important behaviors of your app. Run them after every AI-generated change. That alone puts you ahead of most vibe coders who test nothing.

One more thing

If you're writing Go, samurai was designed with AI-assisted development in mind. The API is one method (s.Test()) - small enough to explain to a model in a single prompt - and every test runs in complete isolation, so AI-generated code with unexpected side effects can't break neighboring checks. Each test is a self-contained path with its own setup and teardown. The AI rewrites your code, you run the tests, each path either passes or fails independently. No cascading failures. Zero dependencies, parallel by default: go get github.com/zerosixty/samurai.

Why Does Your Testing Framework Need 17 Functions?

Stepan Romankov — Fri, 27 Feb 2026 11:42:42 +0000

I counted Ginkgo's top-level API once. Describe, Context, When, It, Specify, By, BeforeEach, AfterEach, BeforeAll, AfterAll, JustBeforeEach, JustAfterEach, BeforeSuite, AfterSuite, SynchronizedBeforeSuite, SynchronizedAfterSuite, DeferCleanup. That's 17, and I stopped counting. There are more if you include the F and P prefixed variants for focus and pending.

GoConvey is leaner but still has Convey, So, ShouldEqual, SkipConvey, FocusConvey, Reset, and its own assertion DSL.

I kept asking myself: what's the minimum API a scoped testing framework actually needs? Not "what's nice to have" -- what's the floor?

Turns out it's one method.

The entire API

s.Test("name", fn)           // leaf test
s.Test("name", fn, builder)  // parent with children
s.Skip()                     // skip this scope

That's samurai. The full public surface fits on a napkin:

func Run(t *testing.T, builder func(*Scope), opts ...Option)
func RunWith[V Context](t, factory, builder, opts...)

type TestScope[V Context]  // one method: Test()
type Scope = TestScope[W]  // alias for the common case
type W = *BaseContext       // has Testing() and Cleanup()

Sequential()  // option
Parallel()    // option (default)

I'm not going to pretend that smaller is automatically better. Ginkgo's BeforeAll exists because people need it. But I do think the Go testing ecosystem has a complexity problem, and most of that complexity exists to manage shared mutable state between tests. If you remove the shared state, the API surface collapses.

The tradeoff

Here's what samurai does that might bother you at first: the builder function runs more than once.

samurai.Run(t, func(s *samurai.Scope) {
    var db *sql.DB  // this gets allocated multiple times

    s.Test("with database", func(ctx context.Context, w samurai.W) {
        db = openTestDB(ctx)
        w.Cleanup(func() { db.Close() })
    }, func(s *samurai.Scope) {
        s.Test("can ping", func(ctx context.Context, w samurai.W) {
            assert.NoError(w.Testing(), db.PingContext(ctx))
        })
        s.Test("can query", func(ctx context.Context, w samurai.W) {
            _, err := db.QueryContext(ctx, "SELECT 1")
            assert.NoError(w.Testing(), err)
        })
    })
})

Two leaf tests, so the builder runs twice. Each run gets its own db. The "with database" callback opens a fresh connection each time. can ping and can query never share a database handle.

This is the point. If you run can ping and can query in parallel (which samurai does by default), they're operating on completely different databases. There is no race. There is no mutex. There is no "who closes the connection first" problem. The isolation comes from the execution model, not from discipline.

Compare this with the BeforeEach pattern where setup runs once and two siblings share the result. That works until someone adds t.Parallel() and discovers the hard way that their *sql.DB pointer is getting reassigned mid-query by the other goroutine.

Side by side

Ginkgo:

var db *sql.DB

BeforeEach(func() {
    db = openTestDB()
    DeferCleanup(func() { db.Close() })
})

It("can ping", func() {
    Expect(db.Ping()).To(Succeed())
})

It("can query", func() {
    _, err := db.Query("SELECT 1")
    Expect(err).NotTo(HaveOccurred())
})

Samurai:

var db *sql.DB

s.Test("with database", func(ctx context.Context, w samurai.W) {
    db = openTestDB(ctx)
    w.Cleanup(func() { db.Close() })
}, func(s *samurai.Scope) {
    s.Test("can ping", func(ctx context.Context, w samurai.W) {
        assert.NoError(w.Testing(), db.PingContext(ctx))
    })
    s.Test("can query", func(ctx context.Context, w samurai.W) {
        _, err := db.QueryContext(ctx, "SELECT 1")
        assert.NoError(w.Testing(), err)
    })
})

Roughly the same line count. The difference is what happens at runtime. In the Ginkgo version, db is shared. In the samurai version, each leaf gets its own db because the whole closure re-runs.

What samurai doesn't have

No BeforeAll. If you need shared infrastructure across tests (a container, a server), set it up in TestMain or at the top of your test function. The framework won't help you share state between paths because that's the thing it's designed to prevent.

No built-in assertions. Use testify, use is, use t.Errorf. The RunWith generic variant lets you embed an assertion library into the test context so you don't have to pass t everywhere, but that's optional.

No Focus or Pending variants of Test. You skip with s.Skip() on the scope. You focus with go test -run. Standard Go.

Try it

go get github.com/zerosixty/samurai

Requires Go 1.24+ (for generic type aliases and t.Context()). Zero dependencies.

github.com/zerosixty/samurai

Testing Telegram Bots in CI/CD: Zero Tokens Required

Stepan Romankov — Mon, 26 Jan 2026 16:00:00 +0000

Last month I watched a colleague's PR sit in review for three days. Not because the code was bad—it was a simple bug fix, maybe twenty lines. The problem was CI. Every time he pushed, the pipeline would run for fifteen minutes, then fail on some random test. He'd re-run it. Sometimes it passed. Sometimes it didn't. By day three, reviewers had moved on to other things.

When I looked at the logs, the pattern was familiar. The tests were hitting Telegram's real API. Some failed due to rate limits. Others timed out waiting for responses. One particularly creative failure happened because the test bot's token had been rotated and nobody updated the CI secret.

This is the story of how we fixed that pipeline—and how you can build a Telegram bot test suite that runs in CI/CD without any API tokens, network access, or prayers to the demo gods.

The Hidden Cost of "Real" Integration Tests

Let's talk about what happens when you test against the real Telegram API in CI.

The token problem. You need a bot token to talk to Telegram. Where does that token come from in CI? Usually a secret. Now you have a secret to manage. Someone rotates it and forgets to update GitHub. Someone copies the workflow file to a new repo and wonders why tests fail. Someone accidentally logs the token in a debug statement and now you're scrambling to revoke it.

Secrets management sounds simple until you're debugging why your nightly build has been red for a week.

The network problem. CI runners live in data centers. Data centers have firewalls, proxies, and occasionally, network issues. Telegram's servers are fast, but "fast" still means 50-200ms per request. A test that sends ten messages takes at least half a second just in network latency. A test suite with a hundred such tests? You're looking at a minute of pure waiting, assuming nothing times out.

And things do time out. I've seen tests that pass locally fail in CI because the runner happened to be in a region with higher latency to Telegram's servers. These failures are maddening because they're not reproducible. Run the same test again and it might pass.

The rate limit problem. Telegram enforces limits on how fast bots can send messages. The exact limits depend on factors Telegram doesn't fully document, but roughly: send too many messages too fast, and you get temporarily blocked. Run fifty tests in parallel, each sending a few messages, and you'll hit those limits. Now your tests fail not because of bugs, but because you're testing too enthusiastically.

The "solution" most teams reach for is running tests sequentially and adding sleeps between them. This works until your test suite grows. Sequential tests with network latency and artificial delays add up fast. What started as a two-minute pipeline becomes ten minutes, then twenty.

The flakiness spiral. Developers stop running the full suite locally. They push and pray. CI becomes a bottleneck instead of a safety net. When a test fails, the first instinct is "re-run it" rather than "investigate it." Eventually, certain tests get marked as "known flaky" and ignored entirely. That's not testing. That's theater.

The Solution: Mock Locally, Test Everything

Here's the thing about teloxide bots: they don't actually care about Telegram. They care about an HTTP endpoint that speaks the Telegram Bot API protocol. By default, that endpoint is api.telegram.org. But it doesn't have to be.

teremock spins up a local HTTP server that implements 40+ Telegram Bot API methods. When you create a MockBot, it configures the teloxide Bot to use localhost instead of Telegram. Your handlers run exactly as they would in production—the state machine transitions, the database queries execute, the responses get sent—except there's no network call leaving the machine.

If you're new to teremock, check out the introduction article for the basics. This article focuses specifically on getting everything working in CI/CD.

The Simplest CI Pipeline

Let's start with a bot that doesn't use a database. Here's the complete GitHub Actions workflow:

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Swatinem/rust-cache@v2
      - run: cargo test --workspace

That's it. No secrets block. No environment variables. No special network configuration.

Compare this to what you'd need for real API tests:

# The old way - don't do this
env:
  TELOXIDE_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
  # Plus handling for rate limits, retries, timeouts...

The teremock approach eliminates an entire category of CI configuration. No tokens to rotate. No secrets to manage across repositories. No "why is this environment variable not set" debugging sessions.

The speed difference is dramatic too. Network round-trips that took 50-200ms each now take microseconds. A test suite that took five minutes against the real API finishes in fifteen seconds.

Adding PostgreSQL for Stateful Bots

Most production bots aren't stateless. They track conversations, store user preferences, manage orders or subscriptions. That state typically lives in PostgreSQL.

GitHub Actions makes it easy to spin up a PostgreSQL service container. Here's the complete workflow:

name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v4
      - uses: Swatinem/rust-cache@v2

      - name: Run tests
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost/test_db
        run: cargo test --workspace

Let's break down what's happening here.

The services block tells GitHub Actions to start a PostgreSQL container before your job runs. The container gets a health check configured so the job waits until PostgreSQL is actually ready to accept connections—no more "connection refused" race conditions.

The ports mapping exposes PostgreSQL on the standard port 5432. From your test code's perspective, it's just a normal PostgreSQL server running on localhost.

The DATABASE_URL environment variable tells sqlx where to connect. This same variable works for both running migrations and for #[sqlx::test] to create isolated test databases.

One important detail: the health check options. Without them, your tests might start before PostgreSQL finishes initializing, leading to sporadic "connection refused" failures. The --health-cmd pg_isready tells Docker to verify PostgreSQL is actually accepting connections before declaring the container healthy.

Parallel Database Tests in CI

If your tests use #[serial] to avoid database conflicts, they'll run sequentially even in CI. That's slow. For a deep dive into parallel database testing with #[sqlx::test], see the parallel database testing article.

The short version: #[sqlx::test] creates a fresh database for each test, runs your migrations, and drops it afterward. Tests can't interfere with each other because they're literally talking to different databases. This enables full parallelism—on an 8-core CI runner, 8 tests run simultaneously.

The CI workflow above already supports this. The DATABASE_URL points to a PostgreSQL server where sqlx can create temporary databases. No additional configuration needed.

Caching for Faster Builds

The Swatinem/rust-cache@v2 action caches your compiled dependencies between runs. This typically cuts build times by 60-80% on subsequent runs.

- uses: Swatinem/rust-cache@v2
  with:
    cache-on-failure: true

The cache-on-failure: true option is useful during development—even if tests fail, you still cache the successful compilation. This speeds up the "fix and re-run" cycle.

For workspaces with multiple crates, the cache handles everything automatically. For monorepos with separate Cargo.toml files (like an examples/ directory), you might need additional configuration:

- uses: Swatinem/rust-cache@v2
  with:
    workspaces: |
      .
      examples

Adding Clippy and Formatting Checks

A complete CI pipeline usually includes more than just tests. Here's what the teremock repository uses:

name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v4
      - uses: Swatinem/rust-cache@v2
        with:
          cache-on-failure: true

      - name: Check formatting
        run: cargo fmt --all -- --check

      - name: Clippy
        run: cargo clippy --workspace --all-targets -- -D warnings

      - name: Run tests
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost/postgres
        run: cargo test --workspace

The order matters here. Formatting checks are instant—if someone forgot to run cargo fmt, fail fast rather than waiting for compilation. Clippy runs next because it catches issues during compilation. Tests run last since they take the longest.

The -D warnings flag for Clippy treats warnings as errors. This prevents "I'll fix that warning later" from becoming "that warning has been there for six months."

Environment Variables and Secrets

One of the biggest wins of mock-based testing is eliminating secrets from CI. But you might still need environment variables for other purposes—database URLs, feature flags, test configuration.

For non-sensitive values, define them directly in the workflow:

env:
  DATABASE_URL: postgres://postgres:postgres@localhost/test_db
  RUST_LOG: debug
  MY_FEATURE_FLAG: enabled

For values that differ between environments, use GitHub's environment variables feature:

- name: Run tests
  env:
    DATABASE_URL: ${{ vars.DATABASE_URL }}
  run: cargo test

Note the difference: secrets.X for sensitive values, vars.X for non-sensitive configuration. Using vars instead of secrets means values show up in logs, making debugging easier.

Handling Test Failures

When tests fail in CI, you need enough information to debug without re-running locally. A few techniques help:

Preserve test output. By default, Cargo captures test output and only shows it for failures. The --nocapture flag shows all output, but that's usually too noisy. Instead, use RUST_LOG to control verbosity:

- name: Run tests
  env:
    RUST_LOG: my_bot=debug
    DATABASE_URL: postgres://postgres:postgres@localhost/test_db
  run: cargo test --workspace

Upload artifacts on failure. If your tests generate logs or other artifacts, upload them:

- name: Upload logs on failure
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: test-logs
    path: target/test-logs/

Matrix testing for multiple Rust versions. If you support multiple Rust versions, test them all:

strategy:
  matrix:
    rust: [stable, beta, 1.83]

steps:
  - uses: actions/checkout@v4
  - uses: dtolnay/rust-toolchain@master
    with:
      toolchain: ${{ matrix.rust }}

The Complete Production Pipeline

Putting it all together, here's a battle-tested CI configuration for a Telegram bot with database persistence:

name: CI
on:
  push:
    branches: [main]
  pull_request:

env:
  CARGO_TERM_COLOR: always

jobs:
  ci:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v4

      - uses: Swatinem/rust-cache@v2
        with:
          cache-on-failure: true

      - name: Check formatting
        run: cargo fmt --all -- --check

      - name: Clippy
        run: cargo clippy --workspace --all-targets -- -D warnings

      - name: Run tests
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost/postgres
        run: cargo test --workspace

      - name: Upload test artifacts on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: test-output
          path: target/
          retention-days: 7

This pipeline:

Starts PostgreSQL before tests run
Caches dependencies for faster subsequent runs
Fails fast on formatting issues
Catches lint warnings with Clippy
Runs all tests in parallel with database isolation
Preserves artifacts if something fails

Total runtime on a warm cache: 2-3 minutes. Most of that is compilation. The tests themselves take seconds.

What You Don't Need Anymore

Let me be explicit about what this approach eliminates:

No TELOXIDE_TOKEN secret. The mock server doesn't need a real token.
No retry logic for flaky network tests. There's no network to be flaky.
No rate limit handling. The mock server doesn't rate limit.
No --test-threads=1 to avoid conflicts. Database isolation handles that.
No "known flaky" test annotations. Tests either pass or fail deterministically.
No special network configuration. Everything runs on localhost.

The pipeline my colleague was fighting with? After migrating to this approach, it went from fifteen minutes with random failures to three minutes with consistent passes. The PR that sat in review for three days would have merged in an hour.

That's the goal: CI that helps you ship faster, not CI that becomes another thing to debug.

Links:

- Documentation

If you're setting up CI for a Telegram bot and run into issues, open an issue on GitHub. I've debugged more pipeline configurations than I'd like to admit, and I'm happy to help.

From 5 Minutes to 15 Seconds: Parallel Database Tests for Telegram Bots

Stepan Romankov — Fri, 23 Jan 2026 08:25:56 +0000

Your test suite takes 5 minutes to run. You make a small change, hit cargo test, and wait. And wait. You check Twitter. Still waiting. By the time tests finish, you've forgotten what you were working on.

I've been there. My phrase_bot had 10 database tests. Each one needed a clean database. The "safe" solution? Run them sequentially with #[serial]. The result? A coffee break every time I ran the suite.

Then I discovered how to combine #[sqlx::test] with teremock and everything changed. Same tests, but running in parallel with complete isolation. No cleanup code. No flaky failures. No more coffee breaks.

This article walks through why traditional database testing is painful, how isolation-based testing solves it, and how to set it up with teremock for your Telegram bot. By the end, you'll have a pattern that scales to hundreds of tests without slowing down.

The Pain of Sequential Database Tests

Let's talk about what most of us do when we first add database tests to a project.

You write your first test. It creates a user, checks something, passes. Great. You write a second test. It also creates a user with the same ID because you copied the first test. Now you have a primary key conflict. Tests fail randomly depending on execution order.

The "obvious" fix is to clean up the database before each test. You write a helper function that deletes everything:

async fn cleanup_database(pool: &PgPool) {
    sqlx::query("DELETE FROM phrases").execute(pool).await.unwrap();
    sqlx::query("DELETE FROM users").execute(pool).await.unwrap();
}

#[tokio::test]
#[serial]
async fn test_create_user() {
    let pool = get_test_pool().await;
    cleanup_database(pool).await;
    // ... test code
}

This works until it doesn't. And it stops working in subtle, frustrating ways.

The ordering problem. You add a phrases table with a foreign key to users. Now DELETE FROM users fails because phrases reference those users. You need to delete phrases first. Every schema change potentially breaks your cleanup function. These bugs don't appear immediately — they appear weeks later when someone adds a foreign key and forgets to update the cleanup order.

The forgotten table problem. You add a settings table. You forget to add it to cleanup. Tests pass locally because you're running them in a certain order. CI runs them differently. Random failures. You spend an hour debugging before realizing the cleanup is incomplete.

The performance problem. To avoid all these race conditions, you slap #[serial] on every test. Now they run one at a time. Ten tests at 500ms each is 5 seconds. Fifty tests is 25 seconds. A hundred tests is almost a minute. You stop running the full suite. You start running "just the tests for this file." Bugs slip through.

The CI flakiness problem. Even with #[serial], I've seen tests that pass locally and fail in GitHub Actions. Different machines, different timing, different connection pooling behavior. The database connection from the previous test hasn't fully closed yet. Or migrations run in a weird order. These are the worst bugs because they're not reproducible locally.

The fundamental issue is that we're trying to reuse a shared resource (the database) across tests that should be independent. We're fighting the architecture instead of working with it.

The Isolation Insight

What if instead of cleaning a shared database, each test got its own database?

Think about it. Test A runs against test_db_abc123. Test B runs against test_db_def456. They can't possibly interfere with each other. They can run in parallel. No cleanup needed — just drop the database when the test ends.

This sounds expensive. Creating and dropping databases has overhead, right?

Yes, but less than you'd think. PostgreSQL can create an empty database in about 50-100ms. That's nothing compared to the time you save by running tests in parallel. If you have 20 tests that each take 500ms, sequential execution takes 10 seconds. Parallel execution with 100ms overhead per test? Under 2 seconds on a multi-core machine.

This is exactly what #[sqlx::test] does. It's a macro from the sqlx crate that:

Creates a fresh database with a unique name before your test runs
Runs your migrations automatically
Passes a connection pool to your test function
Drops the database after the test completes (pass or fail)

#[sqlx::test(migrator = "crate::db::MIGRATOR")]
async fn test_create_user(pool: PgPool) {
    // This pool connects to a brand new database
    // Named something like: myapp_test_a7f3b2c1
    // No other test can see this data
    // Dropped automatically when the test ends
}

The beauty is in what you don't have to write. No cleanup functions. No #[serial]. No careful ordering of deletions. The isolation is handled at the database level, which is exactly where it should be.

Integrating with teremock

Here's where it gets interesting for Telegram bot developers. teremock already gives you isolated bot instances — each MockBot has its own mock server on a random port. Combining that with #[sqlx::test] gives you complete test isolation: isolated bot, isolated database, fully parallel execution.

The setup requires two pieces. First, you need to export your migrator so sqlx can find your migrations:

// src/db/mod.rs
pub static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!("./migrations");

This is a static reference to your migrations directory. The sqlx::migrate! macro reads the migration files at compile time, so there's no runtime file system access.

Second, you write your tests using #[sqlx::test] instead of #[tokio::test], and you inject the pool into your MockBot:

#[sqlx::test(migrator = "crate::db::MIGRATOR")]
async fn test_start_creates_user(pool: PgPool) {
    let mut bot = MockBot::new(
        MockMessageText::new().text("/start"),
        handler_tree()
    ).await;

    // This is the critical line — inject the isolated database
    bot.dependencies(dptree::deps![pool.clone()]);

    bot.dispatch().await;

    let user = db::get_user(&pool, MockUser::ID as i64).await.unwrap();
    assert!(user.nickname.is_none());
}

The pool parameter is your isolated database. When you inject it into the bot's dependencies, all your handlers that expect a PgPool will receive this isolated instance. Your handler code doesn't change at all — it still accepts pool: PgPool and runs queries against it. But in tests, that pool points to a database that exists only for this one test.

Testing Complex Flows

The real payoff comes when you're testing multi-step dialogues with database interactions.

My phrase_bot lets users create custom phrases through a conversation. The user clicks "Add phrase," enters an emoji, enters a trigger word, enters a response template, and the bot saves it to the database. Testing this requires both dialogue state and database state to work together.

With the old approach, I'd need to carefully set up the database, run through the dialogue, verify the result, then clean up. If another test also created phrases, I'd need #[serial] to prevent conflicts. The test file became a minefield of ordering dependencies.

With #[sqlx::test], each test is completely self-contained:

#[sqlx::test(migrator = "crate::db::MIGRATOR")]
async fn test_add_phrase_flow(pool: PgPool) {
    // Create the user this test needs
    db::create_user(&pool, MockUser::ID as i64).await.unwrap();

    let mut bot = MockBot::new(
        MockMessageText::new().text("/start"),
        handler_tree()
    ).await;
    bot.dependencies(deps![get_test_storage(), pool.clone()]);

    // Walk through the dialogue
    bot.dispatch().await;
    bot.update(MockMessageText::new().text("Add phrase"));
    bot.dispatch().await;

    // ... user enters emoji, trigger text, response template ...

    // Verify it saved to OUR database (not shared with anyone)
    let phrases = db::get_user_phrases(&pool, MockUser::ID as i64).await.unwrap();
    assert_eq!(phrases[0].emoji, "🤗");
}

Now I can write a deletion test that also uses the same user ID:

#[sqlx::test(migrator = "crate::db::MIGRATOR")]
async fn test_delete_phrase_flow(pool: PgPool) {
    // Set up a phrase to delete
    db::create_user(&pool, MockUser::ID as i64).await.unwrap();
    db::create_phrase(&pool, MockUser::ID as i64, "🤗", "hug", "...").await.unwrap();

    let mut bot = MockBot::new(/* ... */).await;
    bot.dependencies(deps![get_test_storage(), pool.clone()]);

    // ... navigate to delete, confirm deletion ...

    let phrases = db::get_user_phrases(&pool, MockUser::ID as i64).await.unwrap();
    assert!(phrases.is_empty());
}

Both tests use MockUser::ID. Both manipulate phrases. With #[serial] and shared databases, that's a conflict waiting to happen. With #[sqlx::test], they run in parallel without a care in the world. Different databases, no interference.

This changes how you think about test design. You stop worrying about "what state will the database be in when this test runs?" Each test defines its own preconditions. Each test is a fresh start. The cognitive load drops dramatically.

Performance: The Numbers

I ran benchmarks on my phrase_bot test suite to quantify the difference. Here's what I found:

Approach	8 tests	20 tests	50 tests
`#[serial]` + cleanup	4.2s	10.5s	26.3s
`#[sqlx::test]` parallel	1.1s	1.8s	3.2s

The speedup is 4-8x, and the gap widens as you add more tests.

Why? Sequential execution scales linearly with test count. If each test takes 500ms, 50 tests take 25 seconds. There's no way around it.

Parallel execution scales with your CPU cores. On my 8-core machine, 8 tests that each take 500ms complete in roughly 600ms (500ms for the test plus ~100ms database overhead). The marginal cost of additional tests is just the overhead of creating the database, not the execution time.

The practical impact is huge. 26 seconds is "I'll check my phone while this runs." 3 seconds is "already done before I looked away." When tests are fast, you run them more often. When you run them more often, you catch bugs earlier. Earlier bugs are cheaper to fix.

Gotchas and Solutions

After using this pattern for several months, I've hit a few recurring issues.

Forgetting to inject the pool is the most common mistake. Your test runs, your bot dispatches, and nothing happens. No error, just silence. The handler tried to access the database, got a different pool (or none), and quietly failed.

// Wrong: bot has no access to your test database
bot.dispatch().await;

// Right: inject dependencies BEFORE dispatch
bot.dependencies(deps![pool.clone()]);
bot.dispatch().await;

Make this a habit: MockBot::new(), then dependencies(), then dispatch(). Every time.

Connection limits can bite you with large test suites. PostgreSQL has a default max_connections setting (usually 100). If you're running 50 tests in parallel, each with its own connection pool, you might exceed that limit.

Solutions, in order of preference:

Use PgBouncer for connection pooling
Increase max_connections in postgresql.conf
Limit test parallelism: cargo test -- --test-threads=4

Missing DATABASE_URL is another gotcha. #[sqlx::test] needs to know where to create test databases. It reads DATABASE_URL from the environment and uses that server to create/drop the temporary databases. Make sure your .env file has it set, or export it in your shell before running tests.

When Not to Use This

No technique is universally applicable. Here's when you might skip #[sqlx::test]:

Very small test suites. If you have 3 tests that run in 200ms total, the overhead of creating databases isn't worth it. Just use #[serial] and move on.

Tests that intentionally share state. Sometimes you want test B to see data created by test A. This is rare and often a code smell, but if you genuinely need it, isolated databases won't work.

SQLite in-memory databases. SQLite's in-memory mode creates a new database per connection automatically. You already have isolation. #[sqlx::test] still works, but you're not gaining much.

Tests hitting external services. If your tests call real APIs (payment processors, third-party services), parallel execution might trigger rate limits. Though arguably, those calls should be mocked anyway.

Making the Switch

If you're convinced and want to migrate an existing test suite, here's the process:

Add the migrator export. Create pub static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!("./migrations"); in your database module.
Ensure DATABASE_URL is set. Add it to .env or your CI environment variables.
Convert tests one at a time. Replace #[tokio::test] with #[sqlx::test(migrator = "crate::db::MIGRATOR")]. Add pool: PgPool as the first parameter. Add bot.dependencies(deps![pool.clone()]).
Remove cleanup code. Delete your cleanup_database() function. Delete #[serial] attributes.
Run and verify. Run cargo test and watch them execute in parallel. Check that all tests still pass.

The conversion is mechanical. Most tests require changing 3-4 lines. The payoff is immediate — your test suite gets faster with every test you convert.

Wrapping Up

The combination of teremock for bot mocking and #[sqlx::test] for database isolation transformed my testing workflow. What used to take 5 minutes now takes 15 seconds. What used to fail randomly in CI now passes reliably every time.

But the real win isn't the speed. It's the simplicity. No cleanup functions to maintain. No ordering dependencies to track. No #[serial] attributes to remember. Each test is an island, complete and self-sufficient.

When the feedback loop is fast, you test more. When tests are simple, you write more of them. When you have more tests, you ship fewer bugs.

That's the goal, isn't it?

Acknowledgments

The approach to mock testing for teloxide bots was pioneered by the teloxide_tests project, which served as a major source of inspiration for teremock's architecture and design patterns.

Special thanks to the teloxide team for building such an excellent framework. Without their work, the Rust Telegram bot ecosystem would be a very different place.

If this article was helpful, consider starring the repo on GitHub. Found a bug or have a question? Open an issue and we'll figure it out together.

How I Stopped Worrying and Started Testing My Telegram Bots

Stepan Romankov — Wed, 21 Jan 2026 12:40:38 +0000

A story about testing Telegram bots without the pain

Have you ever shipped a Telegram bot and immediately regretted it? Maybe your /start command crashed spectacularly at 3 AM, or that callback button you "definitely tested" decided to ghost your users. I've been there. Testing Telegram bots traditionally meant one of two things: manually clicking through your bot like a QA intern, or setting up elaborate integration tests that require actual API tokens and network access.

Neither is fun. Neither scales. And both make CI pipelines cry.

That's why I built teremock — a testing library that lets you write fast, reliable tests for your teloxide bots without ever hitting the real Telegram API.

Let me show you what I mean.

The Problem with Testing Telegram Bots

Picture this: you've got a calculator bot. Users send /start, click a button to add or subtract, enter two numbers, and get a result. Simple enough. But how do you test it?

Option 1: Manual testing. You open Telegram, type commands, click buttons, and hope everything works. Rinse and repeat after every code change. This doesn't scale.

Option 2: Real API testing. You set up a test bot token, hit the actual Telegram servers, and pray your internet is stable. Tests take forever because network requests aren't exactly speedy. Good luck running this in CI without exposing credentials.

Option 3: Mock everything yourself. You spend more time building test infrastructure than actual features. Eventually, you question your life choices.

There had to be a better way.

Enter teremock

teremock (Telegram · Realistic · Mocking) takes a different approach. It spins up a lightweight mock server that pretends to be the Telegram Bot API. Your bot talks to this server instead of the real one. From your bot's perspective, nothing changes — it's making the same API calls it always does. But now those calls are instant, offline, and completely under your control.

Here's the simplest possible test:

use teremock::{MockBot, MockMessageText};

#[tokio::test]
async fn test_hello_world() {
    // Create a mock message (as if a user sent "Hi!")
    let mock_message = MockMessageText::new().text("Hi!");

    // Create a bot with your handler tree
    let mut bot = MockBot::new(mock_message, handler_tree()).await;

    // Dispatch the update through your handlers
    bot.dispatch().await;

    // Check what your bot sent back
    let responses = bot.get_responses();
    assert_eq!(
        responses.sent_messages.last().unwrap().text(),
        Some("Hello World!")
    );
}

That's it. No API tokens. No network. No waiting. Just fast, deterministic tests.

Let's Build Something Real

Enough theory. Let's test an actual stateful bot — a simple calculator that walks users through adding or subtracting numbers.

First, here's the handler setup (the part you'd normally write anyway):

use teloxide::{
    dispatching::{dialogue::InMemStorage, UpdateFilterExt, UpdateHandler},
    dptree::deps,
    prelude::*,
};

#[derive(Clone, Default)]
pub enum State {
    #[default]
    Start,
    AwaitingFirstNumber { operation: String },
    AwaitingSecondNumber { operation: String, first: i64 },
}

type MyDialogue = Dialogue<State, InMemStorage<State>>;

fn handler_tree() -> UpdateHandler<Box<dyn std::error::Error + Send + Sync + 'static>> {
    dptree::entry()
        .branch(Update::filter_message().enter_dialogue::<Message, InMemStorage<State>, State>()
            // ... your handler branches here
        )
}

Now the fun part — testing the entire conversation flow in one test:

use teremock::{MockBot, MockCallbackQuery, MockMessageText};
use teloxide::dptree::deps;

#[tokio::test]
async fn test_full_addition_flow() {
    // Start with /start command
    let mut bot = MockBot::new(
        MockMessageText::new().text("/start"),
        handler_tree()
    ).await;

    // Inject your storage dependency
    bot.dependencies(deps![InMemStorage::<State>::new()]);

    // User sends /start
    bot.dispatch().await;
    assert_eq!(
        bot.get_responses().sent_messages.last().unwrap().text(),
        Some("What do you want to do?")
    );

    // User clicks the "add" button
    bot.update(MockCallbackQuery::new().data("add"));
    bot.dispatch().await;
    assert_eq!(
        bot.get_responses().sent_messages.last().unwrap().text(),
        Some("Enter the first number")
    );

    // User enters first number
    bot.update(MockMessageText::new().text("5"));
    bot.dispatch().await;
    assert_eq!(
        bot.get_responses().sent_messages.last().unwrap().text(),
        Some("Enter the second number")
    );

    // User enters second number
    bot.update(MockMessageText::new().text("4"));
    bot.dispatch().await;
    assert_eq!(
        bot.get_responses().sent_messages.last().unwrap().text(),
        Some("Your result: 9")
    );
}

Notice what's happening here:

One test, full conversation. No need to split your flow into five separate tests.
Natural state transitions. The dialogue state updates through your actual handlers, not manual manipulation.
Real dependency injection. Your InMemStorage works exactly like in production.

What About Edge Cases?

Great bots handle weird inputs gracefully. Let's test that:

#[tokio::test]
async fn test_invalid_number_input() {
    let mut bot = MockBot::new(
        MockMessageText::new().text("/start"),
        handler_tree()
    ).await;
    bot.dependencies(deps![InMemStorage::<State>::new()]);

    // Get to the "enter first number" state
    bot.dispatch().await;
    bot.update(MockCallbackQuery::new().data("add"));
    bot.dispatch().await;

    // User sends garbage instead of a number
    bot.update(MockMessageText::new().text("not a number"));
    bot.dispatch().await;
    assert_eq!(
        bot.get_responses().sent_messages.last().unwrap().text(),
        Some("Please enter a valid number")
    );

    // User sends a photo for some reason
    bot.update(MockMessagePhoto::new());
    bot.dispatch().await;
    assert_eq!(
        bot.get_responses().sent_messages.last().unwrap().text(),
        Some("Please send text")
    );

    // User finally sends a valid number
    bot.update(MockMessageText::new().text("5"));
    bot.dispatch().await;
    assert_eq!(
        bot.get_responses().sent_messages.last().unwrap().text(),
        Some("Enter the second number")
    );
}

This test covers three scenarios in one function: invalid text, wrong message type, and recovery. Your error handling actually gets tested.

Digging Deeper: Request Inspection

Sometimes you need to verify more than just the message text. Maybe you're testing that your bot uses the right parse mode, or that a photo is marked as a spoiler. teremock gives you full access to both the sent message and the original request:

#[tokio::test]
async fn test_message_formatting() {
    let mut bot = MockBot::new(
        MockMessageText::new().text("/styled"),
        handler_tree()
    ).await;

    bot.dispatch().await;

    let responses = bot.get_responses();

    // Check the message content
    let response = &responses.sent_messages_text.last().unwrap();
    assert_eq!(response.message.text(), Some("<b>Bold</b> text"));

    // Verify the parse mode in the original request
    assert_eq!(response.bot_request.parse_mode, Some(ParseMode::Html));
}

For media messages, this becomes even more useful:

#[tokio::test]
async fn test_photo_with_spoiler() {
    let mut bot = MockBot::new(
        MockMessageText::new().text("/secret_photo"),
        handler_tree()
    ).await;

    bot.dispatch().await;

    let photo = &bot.get_responses().sent_messages_photo.last().unwrap();
    assert_eq!(photo.message.caption(), Some("Mystery image!"));
    assert!(photo.bot_request.has_spoiler.unwrap_or(false));
}

The Performance Story

Here's where teremock really shines. The mock server starts once when you create a MockBot and persists across all your dispatches. No server restart between interactions.

The numbers speak for themselves:

Scenario	teremock	Server-per-dispatch
50 sequential dispatches	~2 seconds	~30-60 seconds

That's 15-30x faster for comprehensive test suites. And because each dispatch runs in its own tokio task, you won't hit stack overflow issues even with dozens of interactions in a single test.

Your CI pipeline will thank you.

What's Under the Hood?

teremock supports 40+ Telegram Bot API methods out of the box:

Messages: sendMessage, sendPhoto, sendVideo, sendAudio, sendVoice, sendDocument, sendAnimation, sendSticker, sendLocation, sendVenue, sendContact, sendPoll, sendDice, sendInvoice, sendMediaGroup, sendChatAction...

Editing: editMessageText, editMessageCaption, editMessageReplyMarkup

Management: deleteMessage, forwardMessage, copyMessage, pinChatMessage, unpinChatMessage...

Callbacks & More: answerCallbackQuery, setMessageReaction, setMyCommands, getFile, getMe...

All the builders follow a fluent pattern:

// Text message with custom sender
let msg = MockMessageText::new()
    .text("Hello from a specific user")
    .from(MockUser::new().id(12345).first_name("Alex").build());

// Callback query with specific data
let query = MockCallbackQuery::new()
    .data("button_clicked")
    .from(MockUser::new().id(12345).build());

// Photo message
let photo = MockMessagePhoto::new()
    .caption("Check this out!");

Getting Started

Add teremock to your dev dependencies:

[dev-dependencies]
teremock = "0.5"

And you're ready to go. Works with #[tokio::test] out of the box.

Links:

GitHub: https://github.com/zerosixty/teremock
Crates.io: https://crates.io/crates/teremock
Documentation: https://docs.rs/teremock

The repository includes several example bots with full test suites:

hello_world_bot — The basics
calculator_bot — Stateful dialogues with callbacks
album_bot — Media group handling
file_download_bot — File operations
phrase_bot — Database integration patterns

Wrapping Up

Testing Telegram bots doesn't have to be painful. With teremock, you can:

Write tests that run in milliseconds, not minutes
Test complete multi-step conversations in single test functions
Verify your bot's behavior without network access or API tokens
Catch edge cases before your users do

The days of manual Telegram testing or flaky network-dependent CI are over.

Acknowledgments

teremock builds upon ideas from teloxide_tests by LasterAlex, which pioneered the concept of mock testing for teloxide bots. That project was a major source of inspiration for this library's approach.

A huge thank you to the teloxide team for building such an excellent Telegram bot framework. Their work makes building Telegram bots in Rust an absolute joy.

Happy testing!