DEV Community: Maesi

How to Mock a Payment Provider So Playwright Can Actually Walk Through It

Maesi — Fri, 31 Jul 2026 16:02:17 +0000

You know that moment when you're setting up e2e tests for a checkout flow and you just... stop? Because wiring up a real payment service for tests feels like a rabbit hole nobody has time for. So you mock the API response, skip the actual payment page, and tell yourself "we'll figure out the real integration later."

And "later" never really comes, does it.

So your tests cover everything around the payment. The cart, the product page, the order confirmation. But the actual checkout? That's just... trusted. You ship it and hope.

And it's not only the tests. Think about that moment in a sprint review when a stakeholder wants to see the checkout flow. Someone has to say "hang on, let me hack a successful payment somehow" and suddenly the demo is a developer fumbling around in a sandbox account. Not a great look. Or a new developer joins the team and wants to understand how the payment flow works. Same problem. There's no clean way to just... try it.

I've seen this pattern a lot. And honestly it makes sense. Integrating with a real payment provider in a test environment means test accounts, API keys that expire, flaky sandbox environments, and data you can't fully control. It's a mess. So people avoid it.

But here's what I kept thinking: what if the mock wasn't just a stubbed API response, but an actual page? A real form that Playwright navigates, fills in, and submits. Just like a real user would. No shortcuts, no intercepted requests, no pretending.

That's what we're going to build. A fully mocked payment service using Mokapi that serves real HTML, fires a Kafka message, and lets your Playwright tests walk through the entire checkout flow end to end. Including the async part where the backend processes the payment and the frontend finally shows "paid."

And because it's a real page, anyone can use it. A stakeholder, a designer, a developer on their first day. No setup, no hacking, no "wait let me fix this first." Just click pay and watch the whole thing work.

Here's what the flow looks like in practice:

If you've used Mokapi before for basic REST or Kafka mocking, this might change how you think about what a mock can actually be.

Mokapi can serve HTML. Here's why that changes everything.

Most developers, when they hear "mock," think of something like this: intercept the request, return a fake response, move on. And that works fine for a lot of cases. Your code calls an endpoint, gets back a JSON blob, renders something.
Done.

But a payment flow isn't really like that. It's not just an API call. It's a whole experience. The user leaves your app, lands on a payment page, fills in their card details, hits pay, and gets redirected back. There's a form. There's validation. There's a redirect. There's an async event that fires on the backend after the payment processes.

If you stub just the API response you're not really testing that flow. You're testing a shortcut version of it. And shortcuts have a way of hiding bugs.

Here's where Mokapi does something most people don't realize it can do. It can serve HTML pages. Not just respond to API calls, but actually act as a web server. So instead of intercepting the redirect to the payment provider and returning a fake success response, you let the redirect happen. Playwright lands on a real page, served by Mokapi. It fills in a form. It clicks pay. Mokapi handles the POST, produces a Kafka message, and redirects back to your app.

From Playwright's perspective, nothing is mocked. It just navigated a checkout flow.

Think about what that means. Your tests are now exercising the actual redirect behavior. The actual form submission. The actual async processing. The only thing that's fake is the payment provider itself, and honestly that's the only part you want to be fake.

And if the mock behaves like the real service, your tests don't need to know they're talking to a mock. That's kind of the whole point.

Meet the example

Alright, let's get concrete. Abstract ideas are nice, but I'd rather show you something you can actually run.

The example we're building is a simple online shop. Nothing fancy. A frontend, a backend, a shopping cart and a checkout page. The kind of thing you've probably built or worked on a dozen times. The interesting part isn't the shop itself, it's what happens when you hit pay.

In a real setup your backend would call the payment provider's API to create a checkout session, Stripe for example, passing the order amount and a URL to redirect to once payment completes. The provider returns a payment URL, and your frontend redirects the customer there. After payment, the provider fires an event to your backend, typically via a webhook or in our case a Kafka topic, to confirm the payment status. Your backend consumes that event, updates the order, and your frontend shows "paid."

In our setup, Mokapi plays the role of that payment provider. Completely. There are actually two separate mocked services here, and that separation matters. One mocks the payment provider's API, the endpoint your backend calls to create a session. The other mocks the hosted payment page itself, the one the customer's browser actually lands on. In production these would be two different surfaces of the same provider. In our mock they're two different Mokapi configs, which keeps the example honest about who owns what.

Here's the full picture of what's running:

The SUT: a frontend and a backend for the online shop
Mokapi: serving the payment provider API, the payment page, and mocking the Kafka topic
Playwright: running the e2e test, navigating the whole flow

The complete setup is in the GitHub repository. I'll show the relevant pieces here so you understand what's going on, but if you want to dig into the full config and scripts, that's where to go.

Let's start walking through it.

The simulation API: your test's remote control

Sometimes you want to test something specific about the payment flow. Not just the happy path, but what happens during those few seconds while the payment is processing. Does the frontend show a spinner? Does it say "processing"? Or does it just sit there with no feedback at all?

That's what the simulation API is for. One endpoint. POST /simulate/payment-delay lets you configure a delay before Mokapi produces the Kafka message for a specific order. So you can deliberately slow things down and assert what the frontend shows in that window.

await request.post('/simulate/payment-delay', {
  data: {
    orderId: orderId,
    delayMs: 3000
  }
})

Notice it's scoped to a specific orderId, not a global setting. Playwright tests often run in parallel, so a delay configured for one test shouldn't leak into another. Each test reads its own orderId from the checkout page and configures the delay just for that order.

That "processing" state is really easy to forget about when you're building a feature. And even easier to forget to test. But it's what real users see, sometimes for several seconds. With the delay simulation you can test it deliberately, every time, without any timing luck involved.

The payment page

So what does Playwright actually land on when it gets redirected to the mock payment service? A real HTML form. Credit card number, expiry date, CVV. In a real project your team would decide how closely this mirrors the actual payment provider. If you're mocking Stripe you might want to replicate the full Stripe checkout experience, every field, every step, so the test and the demo feel identical to production. That's completely possible with this approach. For this article we're keeping the form simple so we can focus on the mechanics without getting lost in details.

Mokapi serves this page via a GET endpoint defined in an OpenAPI spec. If you haven't done this before it might feel a bit unusual because we're used to OpenAPI describing JSON APIs. But it works just the same for HTML responses. You define the path, the method, and tell it to return text/html. Mokapi takes care of the rest.

paths:
  /payment:
    get:
      summary: Show the payment form
      parameters:
        - name: sessionId
          in: query
          required: true
          schema:
            type: string
          description: The session ID created by the payment provider API
      responses:
        '200':
          description: Payment form
          content:
            text/html:
              schema:
                type: string
    post:
      summary: Process the payment form submission
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                sessionId:
                  type: string
                cardNumber:
                  type: string
                expiry:
                  type: string
                cvv:
                  type: string
      responses:
        '302':
          description: Redirect to successUrl after payment
          headers:
            location:
              schema:
                type: string

The actual HTML is returned by a Mokapi script. And this is where it gets interesting because the script isn't just returning a static string. It's a real handler that receives the request, builds the response, and has full control over what comes back. The form shows the order total and order ID, both of which Mokapi looks up from the session that was created when your backend called the payment provider API.

Simple. Clean. Playwright lands here, sees a form, fills it in. No difference from landing on a real payment page. The full version with styling and error states is in the GitHub repo but this gives you the shape of it.

What happens when you hit Pay

This is where it gets interesting. When Playwright submits the form, Mokapi's script takes over. And it's doing more than just returning a success response. It's behaving like a real payment service would.

It looks up the session, takes the order ID, calls produce() to fire a Kafka message onto the order-payment-state topic, and redirects back to the shop using the success URL that was stored when the session was created.

export default function() {
    on('http', (req, res) => {
        if (req.api !== 'Payment App') {
            return
        }

        if (req.method === 'GET') {
            const sessionId = req.query.sessionId;
            const session = sessions[sessionId]

            if (!session) {
                res.statusCode = 400
                res.data = 'Session not found'
                return
            }

            const html = render(paymentPageTemplate, { sessionId, ...session, error: undefined })
            res.data = html
        } else if (req.method === 'POST') {
            let { sessionId, delay } = req.body
            const session = sessions[sessionId]

            if (!session) {
                res.statusCode = 200
                const html = render(paymentPageTemplate, { sessionId, error: 'Session not found' })
                res.data = html
                return
            }

            const kafkaProduceRequest = {
                topic: 'order-payment-state',
                messages: [
                    {
                        key: session.orderId,
                        data: {
                            orderId: session.orderId,
                            paymentStatus: 'success'
                        }
                    }
                ]
            }

            if (!delay && simulations.payment[session.orderId]) {
                delay = simulations.payment[session.orderId].delayMs
            }

            if (delay > 0) {
                delete simulations.payment[session.orderId]

                setTimeout(() => {
                    produce(kafkaProduceRequest)
                }, delay)
            } else {
                try {
                    produce(kafkaProduceRequest)
                } catch (err) {
                    const html = render(paymentPageTemplate, { sessionId, error: `${err}` })
                    res.data = html
                    return
                }
            }

            res.statusCode = 302
            res.headers = { Location: session.successUrl }
        }
    })
}

One small but useful detail. If produce() fails because the message doesn't match the topic schema, that error surfaces directly on the payment page. So if something is wrong a tester sees it immediately right there, rather than staring at an order that never updates and wondering what happened.

And that Kafka message is real. Your SUT backend is listening to that topic just like it would in production. It consumes the message, updates the order status, and the frontend reflects that. Mokapi didn't fake the outcome. It triggered the actual processing chain.

That's the part worth sitting with for a second. The mock isn't returning a pre-cooked response that bypasses your backend logic. It's producing an event that your backend has to actually handle. If there's a bug in how your backend processes that Kafka message, this test will catch it.

The async part: waiting like a real user

So Playwright just got redirected back to the shop's confirmation page. And here's the thing: the order status might not be "paid" yet. The backend still needs to consume the Kafka message and update the order. That takes a moment. Not long, but a moment.

And you know what? That's fine. That's exactly how it works in production too.

This is something I think is worth being explicit about in your tests. Don't hide the async nature of the flow. Playwright has built in waiting mechanisms that handle this really naturally. Instead of a hardcoded sleep you just wait for the element that shows the payment status to appear with the right value.

await expect(page.getByRole('heading', { name: 'Payment confirmed' })).toBeVisible({ timeout: 30000 });

Playwright will keep checking until it sees "paid" or the timeout hits. Clean, readable, and it mirrors what a real user experiences. They land on the confirmation page and wait a second for it to update.

Now here's where the delay simulation becomes really useful. Remember POST /simulate/payment-delay? If you configure a three-second delay before Mokapi produces the Kafka message for a specific order, you can test what the frontend shows during that window.

await request.post(`${simulationUrl}/simulate/payment-delay`, {
    headers: { 'Content-Type': 'application/json' },
    data: { 
        orderId,
        delayMs: 3000
    },
});

// Now submit the payment form
// Assert the pending state appears first
await expect(page.getByRole('heading', { name: 'Processing your payment' })).toBeVisible();

// Then wait for it to resolve
await expect(page.getByRole('heading', { name: 'Payment confirmed' })).toBeVisible({ timeout: 30000 });

That "processing" state is really easy to forget about when you're building a feature. And even easier to forget to test. With the delay simulation you can test it deliberately, every time, without any timing luck involved.

What Playwright actually sees

Let's zoom out and look at the full test. Because after all the setup we've talked about, the actual Playwright code tells a complete story.

test(name, async ({ page, request, simulationUrl }) => {
    await page.goto('');

    await test.step('Add product to cart', async () => {
        const article = page.getByRole('article', { name: 'Wireless Headphones' })
        await article.getByRole('button', { name: 'Add to cart' }).click();
    });

    await test.step('Verify order details on checkout page', async () => {
        const nav = page.getByRole('navigation');
        await nav.getByRole('button', { name: 'Cart' }).click();

        const shoppingCart = page.getByRole('region', { name: 'Shopping cart items' });
        const cartItems = shoppingCart.getByRole('listitem');
        await expect(cartItems).toHaveCount(1);
        await expect(cartItems.first()).toContainText('Wireless Headphones');
        await expect(cartItems.first()).toContainText('$79.99');
    });

    await test.step('Proceed to checkout', async () => {
        await page.getByRole('button', { name: 'Proceed to checkout' }).click();

        const orderId = await page.getByLabel('Order ID').textContent()

        await request.post(`${simulationUrl}/simulate/payment-delay`, {
            headers: { 'Content-Type': 'application/json' },
            data: { orderId, delayMs: delay },
        });
    })

    await test.step('Pay and verify order completion', async () => {
        await page.getByRole('button', { name: 'Pay' }).click();

        await page.getByRole('textbox', { name: 'Card number' }).fill('4242424242424242');
        await page.getByRole('textbox', { name: 'Expiry' }).fill('12/34');
        await page.getByRole('textbox', { name: 'CVC' }).fill('123');
        await page.getByRole('button', { name: 'Pay' }).click();

        if (delay > 0) {
            await expect(page.getByRole('heading', { name: 'Processing your payment' })).toBeVisible();
        }

        await expect(page.getByRole('heading', { name: 'Payment confirmed' })).toBeVisible({ timeout: 30000 });
    })
});

Read it top to bottom and it tells a story. Open the shop, add a product, go to the cart, proceed to checkout, click pay, get redirected to the payment page, fill in the card details, submit, land back on the shop, wait for confirmation. A new developer on the team can read this and immediately understand the full user journey.

And that redirect in the middle is important. The test isn't jumping directly to the payment form. It clicks the pay button on the shop's checkout page, the backend creates a session with the payment provider and returns a URL, and the redirect happens naturally. That means you're also testing that your backend correctly creates the session and constructs the right redirect URL. That's real behavior being exercised, not skipped.

Notice what the test doesn't know though. It doesn't know Mokapi is serving the payment page. It doesn't know a Kafka message is being produced behind the scenes. It doesn't know the backend is consuming that message asynchronously. It just navigates, interacts, and asserts. Exactly like a real user would.

That separation is what makes this approach so valuable. Your tests describe behavior, not implementation. If you eventually point the tests at a real payment provider, the test itself doesn't change. The flow is the flow.

Why this matters more than you think

Look, there are a lot of ways to fake a payment flow in tests. You can stub the API response, you can skip the checkout entirely and just seed a "paid" order directly in the database, you can flag the user as a test user and bypass the whole thing in code. These approaches work.

But they all have the same blind spot. They're not testing the flow. They're testing around it.

And the flow is where bugs live. The redirect that sends the wrong order ID. The frontend that doesn't handle the "processing" state before the Kafka message arrives. The backend that has a subtle bug in how it parses the payment event. None of these show up when you stub a response or seed a database row. They show up in production, in front of real users, with real money involved.

That's what makes this approach different. You're not testing around the payment flow. You're walking through it, every single time, in a way that's repeatable and automated and available to anyone on the team.

And honestly that last part is underrated. Because it's not just about the tests. A stakeholder can open the app in a staging environment and click through a complete checkout without anyone having to set anything up. A designer can click through the checkout and verify the confirmation page looks right once the payment status comes back. A new developer can run the Playwright suite on their first day and watch the whole flow execute. No sandbox accounts, no test credit card numbers buried in a wiki, no "let me just quickly hack this so you can see it."

The mock is the service. It's always there, it always works, and anyone can use it.

That's a different relationship with your test environment than most teams have. And once you've worked this way it's hard to go back.

What's next

We covered a lot of ground here. A mocked payment provider API and a mocked payment page that Playwright navigates like a real user. A Kafka topic that gets a real message produced onto it. A simulation API that gives your tests a remote control for the scenarios they need. And a test that reads like a user story, not a list of API stubs.

But payment flows are just one example of this pattern. Any external service that takes your user somewhere else and brings them back is a candidate for this approach. And the one that comes up almost as often as payments is identity. Login flows, single sign-on, OAuth redirects. The same problem: your user leaves your app, authenticates somewhere else, and comes back with a token.

That's what the next article is about. Mocking an IDP with Mokapi. Serving a real login form, handling the redirect back to your app, and getting into the slightly thornier territory of tokens and how your backend accepts them in a test environment. There are a few different approaches there and they're worth exploring properly.

For now, grab the GitHub repository and have a look at the full example. The Mokapi config, the scripts, the Playwright tests, all of it is there. Run it, break it, adapt it to
your own setup. And if you've been avoiding testing your payment flow because it felt too hard to mock properly, well. Maybe it's not as hard as you thought.

Originally published on the Mokapi blog. Cross-posting here since I think it's a pattern more teams should know about.

Your Test Suite Shouldn't Depend on APIs You Don't Control

Maesi — Sun, 07 Jun 2026 10:00:00 +0000

You know this feeling. A test passes locally, fails in CI, you rerun it, it passes again. Somewhere a third-party API was slow, or returned something unexpected, or was just briefly down. You move on, but it happens again next week.

And that's before you even get to the scenarios you can't test at all: rate limits, timeouts, malformed responses. You can't make a live API produce those on demand. So those code paths go untested.

Mocking solves both problems. Mokapi gives you a spec-validated mock server driven by your OpenAPI or AsyncAPI specs. Every response conforms to the contract. Every request gets validated. Your tests run against something you fully control.

The CI Setup

Mokapi runs in Docker during your test job. Your app points at it instead of the real API. That's the whole switch.

- name: Start Mokapi
  run: |
    docker run -d --name mokapi \
      -p 80:80 \
      -v ${{ github.workspace }}/mocks:/mocks \
      mokapi/mokapi:latest /mocks
    sleep 5

- name: Run Tests
  run: npm test

- name: Stop Mokapi
  run: docker stop mokapi

Your mock specs live in /mocks in the repo, versioned alongside the code. When the API contract changes, the spec changes, the mock changes, and the tests run against the updated contract automatically.

Simulating the Scenarios That Matter

This is where it gets useful beyond just removing the external dependency. With Mokapi's JavaScript API you can control behavior at runtime without restarting anything.

import { on, sleep } from 'mokapi'

export default () => {
  let delay = undefined

  on('http', (request, response) => {
    if (request.key === '/simulations/delay') {
      switch (request.method) {
        case 'PUT':
          delay = request.query.duration
          break
        case 'DELETE':
          delay = undefined
          break
      }
    }
  }, { track: true })

  on('http', (request, response) => {
    if (delay) {
      sleep(delay)
    }
  }, { track: () => delay !== undefined })
}

Your test sends a PUT to enable a delay, runs the scenario, sends a DELETE to reset. Same pattern works for forcing 500s, 429 rate limits, or any other condition you want to test against.

The track: true on the first handler is worth understanding. Mokapi's dashboard shows every HTTP request with the response and all JavaScript handlers that ran for it. The first handler only updates internal state without touching the response, so Mokapi wouldn't know it was relevant unless you tell it explicitly. track: true keeps it visible in the dashboard, which matters when you're debugging why a test behaved unexpectedly.

What You Actually Get

Consistent test results because nothing outside your control can break them. Coverage of error scenarios that a live API can't reproduce on demand. Faster pipeline runs with no network latency. And because Mokapi validates against the spec, contract violations get caught in CI before they reach production.

Full Walkthrough

The complete guide on mokapi.io covers the full GitHub Actions setup, the JavaScript simulation API, and how to structure your mock specs for a real project.

👉 Read the full guide here

Happy to answer questions in the comments.

API Contracts Break Silently. Here's How to Catch Them the Moment They Do.

Maesi — Sat, 06 Jun 2026 13:00:00 +0000

A backend developer renames a field. The tests pass. It ships. Three days later the mobile app is crashing and nobody knows why.

This is how API contract drift works. It's not a discipline problem. It's a tooling problem. When nothing enforces the contract at runtime, you're relying on everyone to manually keep specs, code, and clients in sync across multiple teams and deploy cycles. That doesn't scale.

I built a validation layer into Mokapi to fix this. The idea is simple: Mokapi sits between your client and backend, validates every request and response against your OpenAPI spec, and gives you an immediate, actionable error the moment something violates the contract.

The Forwarding Script

One JavaScript file is all it takes:

import { on } from 'mokapi'
import { fetch } from 'mokapi/http'

export default async function() {
  on('http', async (request, response) => {
    const url = getForwardUrl(request)

    if (!url) {
      response.statusCode = 500
      response.body = 'Failed to forward request: unknown backend'
      return
    }

    try {
      const res = await fetch(url, {
        method: request.method,
        body: request.body,
        headers: request.header,
        timeout: '30s'
      })

      response.statusCode = res.statusCode
      response.headers = res.headers

      const contentType = res.headers['Content-Type']?.[0] || ''
      if (contentType.includes('application/json')) {
        response.data = res.json()  // triggers response validation
      } else {
        response.body = res.body
      }
    } catch (e) {
      response.statusCode = 500
      response.body = e.toString()
    }
  })

  function getForwardUrl(request) {
    switch (request.api) {
      case 'backend-1':
        return `https://backend1.example.com${request.url.path}?${request.url.query}`
      case 'backend-2':
        return `https://backend2.example.com${request.url.path}?${request.url.query}`
      default:
        return undefined
    }
  }
}

request.api contains the info.title from your OpenAPI spec and is used here purely for routing to the right backend URL.
The choice between response.data and response.body is what controls validation: setting response.data tells Mokapi to validate the response against the spec schema, while setting response.body skips validation entirely. So for JSON responses you want validated, use response.data. For anything else, response.body passes it through as-is.

No changes to your backend. No changes to your client. Just point the client at Mokapi instead.

What It Actually Catches

More than just a renamed field. Mokapi validates:

Request method, URL structure, headers, query parameters
Request body: required fields, data types, format constraints
Response status codes, headers, and body structure

A backend that starts returning a string where the spec says number. A client sending a request body missing a required field. A response body that doesn't match the documented schema. All caught at the boundary, with a message that tells you exactly what violated what.

Where to Use It

It's the same script in every context. Between frontend and backend during local development. Between microservices in CI. In Playwright tests so your test suite becomes a contract test suite automatically. In Kubernetes preview environments before changes reach staging.

Full Walkthrough

The complete guide on mokapi.io covers the full setup.

👉 Read the full guide here

Happy to answer questions in the comments.

Playwright Email Testing: E2E Workflows Without a Real Mail Server

Maesi — Fri, 05 Jun 2026 22:07:45 +0000

Email is one of those things that's genuinely hard to test. It goes out through an SMTP server, lands in a real inbox, and you have no programmatic way to check what arrived. So most teams either test it manually or just assert that sendEmail() was called and call it done.

Neither tells you if the subject line was right, the link was valid, or the HTML rendered correctly.

That's why I built email support into Mokapi. The idea is to streamline Playwright email testing by replacing
the real infrastructure with a mock that your test can inspect. Your backend connects to Mokapi's SMTP server exactly as it would a real mail server. Mokapi captures the message. Your test fetches it over HTTP and asserts on the content. No real emails, no inbox polling, no external dependencies.

The Email Server Mock Config

Unlike Kafka or HTTP, email doesn't have a standard specification format. So Mokapi uses a simple YAML config. This is all you need:

mail: '1.0'
info:
  title: "Email Workflows"
servers:
  smtp:
    host: :2525
    protocol: smtp

Point your backend at localhost:2525 and Mokapi starts capturing everything.

Want IMAP too, so you can preview emails in a real mail client during development? Add one line:

  imap:
    host: :1430
    protocol: imap

The Playwright Email Test

The test drives a real signup form, then fetches the captured email from Mokapi's HTTP API and asserts on it.

test('Email verification after signup', async ({ page, request }) => {
  const recipient = randomEmail();

  // Drive the signup form
  await page.goto('');
  const form = page.getByRole('form', { name: 'Sign Up' });
  await form.getByLabel('Email').fill(recipient);
  await form.getByLabel('Password').fill('SuperSecure123!');
  await form.getByRole('button', { name: 'Sign Up' }).click();
  await expect(form.getByText('Check your inbox to verify your email')).toBeVisible();

  // Fetch the email from Mokapi
  const mails = await request.get(
    `http://localhost:8080/api/services/mail/Email%20Workflows/mailboxes/${recipient}/messages?limit=1`
  );
  const mailList = await mails.json();
  expect(mailList[0]).toEqual(expect.objectContaining({
    subject: 'Verify your email address',
    from: expect.arrayContaining([expect.objectContaining({ address: 'noreply@example.com' })]),
    to: expect.arrayContaining([expect.objectContaining({ address: recipient })])
  }));

  // Check the body and verification link
  const res = await request.get(
    `http://localhost:8080/api/services/mail/messages/${mailList[0].messageId}`
  );
  const mail = await res.json();
  expect(mail.body).toContain(`verify?email=${encodeURIComponent(recipient)}`);
});

Random email per test run keeps things isolated. Playwright's request object handles the Mokapi API calls directly, so the same test that drives the browser also inspects the email. No extra HTTP client needed.

The IMAP Bonus

Automated assertions catch broken content. But they don't catch a layout that looks terrible in Outlook. Because Mokapi supports IMAP, you can connect any real mail client to localhost:1430 during development and see exactly what your users will see. It's the visual check your test suite can't do.

Full Walkthrough

This is the short version. The complete guide on my site covers the full config, the Express backend, all the Playwright helpers, and how it all fits together.

👉 Read the full guide here

Working repo: mokapi-email-workflow

Happy to answer questions in the comments.

Testing Kafka Workflows Without Kafka — With Playwright & Mokapi

Maesi — Wed, 20 Aug 2025 20:30:38 +0000

Event-driven systems are powerful — but testing them can feel heavy.

In event-driven systems, the contract between producers and consumers is everything. A field gets renamed. A schema evolves. A new required property sneaks in. Any of those can silently break a downstream service, and you won't find out until something blows up in production.

That's the problem I built Mokapi to solve. Define your Kafka topics in an AsyncAPI spec, and Mokapi enforces that contract automatically. Every message gets validated against the schema, no matter where it comes from. Change the spec and run your tests. If anything is out of line, you'll know immediately.

Because Mokapi acts as a real Kafka broker on localhost:9092, your service doesn't need to change at all. No special test mode. No stubbed clients. Just your actual code running against a mock that holds it to the contract.

The Idea Behind Mokapi

Mokapi lets you define Kafka topics with an AsyncAPI spec and interact with them over a simple REST API. No broker. No Zookeeper. Your service connects to localhost:9092 exactly like it does in production, but Mokapi is answering. The application code doesn't change at all.

In this article I'm using Mokapi's HTTP API to inject test messages, but Mokapi actually supports several other ways to produce messages too, including a JavaScript API and OpenAPI-backed endpoints with custom handlers.

And in all cases, Mokapi validates every message against your AsyncAPI schema by default. You're not just checking that a message arrived, you're checking it's valid according to the contract.

A Real Workflow Test

Here's the scenario: a backend consumes a command from document.send-command, processes it, and publishes a result to document.send-event. The test acts as the foreign system that sends the command and verifies the outcome.

I use Playwright as the test runner (yes, the browser tool, but it's great for async workflows even without a browser).

test('Kafka document send workflow', async () => {
  const documentId = 'doc-' + Date.now();
  let startOffset = -1;

  await test.step('Record current offset', async () => {
    startOffset = await getPartitionOffset(TOPIC_EVENT, 0);
  });

  await test.step('Produce command', async () => {
    await produce(TOPIC_COMMAND, {
      key: documentId,
      value: { documentId, recipient: 'alice@mokapi.io', ... }
    });
  });

  await test.step('Wait for event and assert', async () => {
    let record;
    const timeout = Date.now() + 5000;

    while (Date.now() < timeout && !record) {
      const records = await read(TOPIC_EVENT, 0, startOffset);
      record = records.find(x => x.value.documentId === documentId);
      if (!record) {
        startOffset += records.length;
        await new Promise(res => setTimeout(res, 200));
      }
    }

    expect(record).not.toBeNull();
    expect(record.value.status).toBe('SENT');
  });
});

The offset tracking is the thing people miss the first time. Without it, you might pick up a stale message from a previous run and get a false positive. Record the offset before you produce, then only read from there.
The backend itself runs completely unchanged, connecting to localhost:9092 as normal. It doesn't know Mokapi is there. That's kind of the whole point.

Why I Think This Matters

The backend isn't mocked. Your actual consumer and producer code runs against a spec-validated broker. You're testing your logic, not simulating it. And because Mokapi starts in seconds with no infrastructure dependencies, this works fine in CI without any special setup.

Full Walkthrough

This is the short version. I wrote a complete guide on my site covering the full AsyncAPI spec, the Node.js backend, all the Playwright helpers, and how to extend this pattern to more complex workflows.

👉 Read the full guide here

Working repo: mokapi-kafka-workflow

Happy to answer questions in the comments if you run into anything.

Acceptance Testing with Mokapi: Focus on What Matters

Maesi — Tue, 08 Jul 2025 11:24:48 +0000

In today’s fast-paced development cycles, it’s crucial to ensure your software meets real user expectations. While unit tests validate internal code, acceptance testing answers the bigger question: Does the system behave as users expect? This post explores the value of acceptance tests and how Mokapi supports it by simulating APIs, validating specifications, and enabling robust, realistic test cases.

Why Acceptance Testing

Software testing is not merely a box to check—it is a fundamental process to answer one critical question: Is our software releasable?

Among the various levels of testing, acceptance testing offers the most direct insight into whether the software meets business and user expectations. It bridges the gap between the world of users and the inner workings of the code by turning expectations into precise, executable checks on system behavior.

The Nature of Acceptance Tests

At its core, an acceptance test is an executable specification of how a system should behave, written from a user’s perspective. It is not concerned with how the system is implemented, but with what it does—its behavior and its outcomes.

While unit tests focus on individual components, acceptance tests focus on the system's intent. They clarify what should happen when a user interacts with the software under certain conditions.

When we get the level of abstraction right, acceptance tests become clear, precise, and maintainable. They reflect scenarios that matter to users, expressed in a way that is both easy to read and easy to execute. They serve as living documentation that evolves with the system and its requirements.

Solving Ambiguity and Ensuring Reproducibility

One of the most challenging aspects of software development is not writing code—it is understanding the problem clearly and expressing it precisely. Programs are, after all, specifications of what we want the system to do. But unlike natural languages, which are rich in context and ambiguity, software requires unambiguous clarity.

This is where acceptance testing shines.

By expressing requirements in an executable form, acceptance tests remove ambiguity. They define exactly what needs to happen. Rather than relying on vague documentation or human interpretation, developers, testers, and stakeholders can rely on concrete, shared understanding. The tests describe behavior, not implementation details, which makes them robust to changes in how the system is built, as long as it continues to behave as expected.

Moreover, acceptance tests are reproducible. They can be run automatically, as often as needed, to ensure the software continues to meet its defined expectations. This reproducibility is crucial for modern CI pipelines, where tests are run continuously to catch regressions early

A Contract of Trust

In a collaborative development environment, acceptance tests serve as a contract between the business and the development team. When everyone agrees on the specifications encoded in the tests, there is no room for misinterpretation. The business gets what it asked for, and developers have a reliable guide to follow.

This contract is especially important in agile and iterative processes, where requirements evolve and features are delivered incrementally. With acceptance tests in place, the team always has a clear picture of what "done" means.

Making Software Releasable

Acceptance testing answers a key question: Is the software ready to release? It gives us confidence that the features meet user needs and work correctly. It also checks that we built what was actually requested. Most importantly, it does this in a way that’s automated, repeatable, and reliable.

By aligning development with user intent, removing ambiguity, and validating results, acceptance testing becomes an essential practice—not just for verifying software, but for clearly understanding and specifying it in the first place.

The problem with acceptance testing and 3rd party APIs

Unstable – External APIs can fail randomly, whether due to bugs or release workflows.
No test environment – Many APIs don’t offer a dedicated environment for testing.
Uncontrollable state – It’s often impossible to set up the external system in the desired state for your tests.

These limitations can make acceptance testing brittle and unreliable—unless you can simulate the external system reliably.

How Mokapi Supports Acceptance Testing

That’s where Mokapi comes in. It lets you simulate realistic API behavior in a way that’s fast, accurate, and under your full control.

Acceptance testing becomes significantly more effective with the right tools—especially in complex environments with multiple APIs, microservices, and evolving interfaces. Mokapi was developed to address precisely these challenges. It provides a powerful, flexible, and specification-oriented approach to API simulation, enabling high-quality acceptance testing in a wide variety of scenarios.

Acceptance Testing Across Boundaries

Mokapi makes acceptance testing easier across flexible system boundaries—whether you're focusing on a single microservice or validating your entire architecture—by mocking the APIs they depend on.

Powerful Flexibility for Real-World Scenarios
With Mokapi, you're not limited to ideal cases. The JavaScript-based mock handlers enable the simulation of a wide variety of real-world scenarios, including negative tests, edge cases, and error conditions—all essential for developing robust software. You can programmatically control responses based on request data, headers, or business logic, giving you precise control over your mock's behavior during a test.

This flexibility helps you answer not only the question "Does it work?" but also "Does it work when third-party systems don't."

Specification-Driven Confidence

One of Mokapi's key strengths is its close alignment with API specifications. Mocks are continuously validated against OpenAPI or AsyncAPI definitions, ensuring they accurately reflect the APIs being simulated. This becomes especially valuable as APIs evolve.

When a provider releases a new API version, it can be easily updated in Mokapi. If mock data or API calls no longer conform to the updated specification, Mokapi returns errors that can be caught through acceptance testing. This supports automated API version updates and acts as an early warning system for potential production issues.

Smart Mock Customization with Patch Mechanism

Mokapi supports a patching mechanism for both API specifications and mock data. Patching the specification helps you adopt new API versions more easily while keeping track of your own modifications to the original spec. Patching mock data, on the other hand, allows you to avoid over-mocking—keeping your tests stable and focused, so changes are only required when they’re truly relevant.

Here's an example:

import { on, patch } from 'mokapi';
import { fake } from 'mokapi/faker';

export default function() {
    // Open the OpenAPI pet store specification, resolving all $ref references
    const api = open('pet-store-api.yaml', { as: 'resolved' });

    // Generate a random pet object based on the OpenAPI schema
    const pet = fake(api.components.schemas.pet);

    on('http', (request, response) => {
        // Use the generated pet but override the name to 'Odie'
        response.data = patch(pet, { name: 'Odie' });

        // Alternatively, patch Mokapi's autogenerated response and just set the name
        // response.data = patch(response.data, { name: 'Odie' });
    });
}

This example demonstrates how you can generate valid mock data that conforms to the API specification and then customize only the parts relevant to your test—such as setting a specific pet name—without redefining the entire response structure.

Making Acceptance Testing Sustainable

By combining flexible mocks, specification validation, and a smart patching mechanism, Mokapi makes acceptance testing more resilient, more focused, and easier to maintain. It helps your team test confidently—whether you're building a new feature in isolation, validating complex integrations, or preparing for a production release.

Mokapi doesn’t just enable acceptance testing—it makes it practical, maintainable, and deeply aligned with your evolving system and its requirements.

Ready to get started?

Learn how to set up acceptance tests with Mokapi in your CI/CD pipeline:

👉 Running Mokapi in a CI/CD Pipeline
👉 Mokapi Documentation