Adds or overrides existing tags that are used in dashboard.
+
+
+
track
+
boolean | (params) => boolean
+
Controls whether this event handler is tracked in the dashboard.
+
+
+
priority
+
integer
+
Defines the execution priority of the event handler. Handlers with a higher value are executed first. If no priority is specified, the default priority is 0.
+
+
+
+
## Example: Adding custom tags
@@ -29,6 +51,62 @@ export default function() {
}
```
+## Example: Controlling whether an event handler is tracked in the dashboard
+
+The track field controls whether executions of an event handler appear in the dashboard.
+
+It supports two modes:
+- true / false — always track or never track
+- a function — decide dynamically per request
+
+### Static tracking
+
+```javascript
+on('http', handler, { track: true })
+```
+
+### Dynamic tracking (function)
+
+```javascript
+on('http', handler, {
+ track: (request, response) => request.key !== '/health'
+})
+```
+
+### Full example: Delay simulation with tracking
+
+```javascript
+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 } )
+}
+```
+
+#### Explanation
+- The first handler exposes a control endpoint to configure the delay.
+ - track: true ensures all configuration changes are visible in the dashboard.
+- The second handler applies the delay to incoming requests.
+ - Tracking is enabled only while a delay is active, keeping the dashboard clean when no simulation is running.
+
## Example: Controlling execution order with priority
When multiple handlers are registered for the same event, the priority
diff --git a/docs/resources/blogs/acceptance-testing.md b/docs/resources/blogs/acceptance-testing.md
index c248b5d9c..80e2e3647 100644
--- a/docs/resources/blogs/acceptance-testing.md
+++ b/docs/resources/blogs/acceptance-testing.md
@@ -1,136 +1,186 @@
---
title: "Acceptance Testing with Mokapi: Focus on What Matters"
description: Discover how Mokapi simplifies acceptance testing with mock APIs for REST or Kafka. Stay aligned with specs, handle edge cases, and test with confidence.
+subtitle: Build confidence in your software with acceptance tests that validate behavior, not implementation. Learn how Mokapi makes testing against external APIs practical and maintainable.
image:
url: "/acceptance-testing.png"
alt: Diagram illustrating acceptance testing as executable specifications interacting with the backend and mocked external APIs using Mokapi.
+tags: [ Testing, CI/CD, Quality]
+links:
+ items:
+ - title: CI/CD Integration Guide
+ href: /resources/tutorials/running-mokapi-in-a-ci-cd-pipeline
+ - title: Guard Your API Contracts
+ href: /resources/blogs/guard-your-api-contracts
---
# Acceptance Testing with Mokapi: Focus on What Matters
-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.
+In fast-paced development cycles, it's crucial to ensure your software meets real user expectations.
+Unit tests validate that individual components work correctly, but they can't answer the bigger question:
+*Does the system behave the way users expect?*
-### The Nature of Acceptance Tests
+That's where acceptance testing comes in, and it's more than just another layer of testing.
+It's a fundamental shift in how we think about software quality.
-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.
+> Is our software releasable?
-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.
+Among all testing levels, acceptance testing offers the most direct insight into whether software meets business and
+user expectations. It bridges the gap between user needs and code implementation by turning expectations into **precise**,
+**executable specifications** of system behavior.
-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.
+## What Makes Acceptance Tests Different
-### Solving Ambiguity and Ensuring Reproducibility
+### Unit Tests vs. Acceptance Tests
-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**.
+**Unit Tests:**
+- Focus on *how* components work internally
+- Test implementation details
+- Fast, isolated, developer-focused
+- Break when implementation changes
+- Answer: "Does this code work?"
-This is where acceptance testing shines.
+**Acceptance Tests:**
+- Focus on *what* the system does
+- Test behavior and outcomes
+- Slower, integrated, user-focused
+- Stable across implementation changes
+- Answer: "Does this system meet expectations?"
-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.
+### Acceptance Tests as Executable Specifications
-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
+At its core, an acceptance test is an *executable specification* of how a system should behave, written from a user's
+perspective. It's not concerned with implementation, only with behavior and outcomes.
-### A Contract of Trust
+When we get the abstraction level right, acceptance tests become **clear, precise, and maintainable**. They reflect
+scenarios that matter to users, expressed in a way that's both easy to read and easy to execute. They serve as
+living documentation that evolves with the system.
-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.
+### Removing Ambiguity, Ensuring Reproducibility
-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.
+One of the hardest challenges in software development isn't writing code, it's understanding the problem
+clearly and expressing it precisely. Software requires unambiguous clarity, unlike natural language which
+thrives on context and implication.
-### Making Software Releasable
+This is where acceptance testing shines:
-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**.
+``` box=benefits title="Removes Ambiguity" emoji=🎯
+By expressing requirements in executable form, tests define exactly what needs to happen, no vague documentation or
+human interpretation required.
+```
-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.
+``` box=benefits title="Ensures Reproducibility" emoji=🔁
+Tests run automatically, as often as needed, catching regressions early and providing consistent results across environments.
+```
-### The problem with acceptance testing and 3rd party APIs
+``` box=benefits title="Creates Shared Understanding" emoji=🤝
+Developers, testers, and stakeholders rely on concrete, shared definitions of behavior rather than assumptions.
+```
-- **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.
+``` box=benefits title="Serves as a Contract" emoji=📜
+When everyone agrees on specifications encoded in tests, there's no room for misinterpretation between business and development.
+```
-These limitations can make acceptance testing brittle and unreliable—unless you can simulate the external system reliably.
+## The Problem: External APIs Break Acceptance Tests
-## How Mokapi Supports Acceptance Testing
+Acceptance tests sound great in theory, but in practice they often depend on external APIs such as payment providers,
+authentication services, notification systems, data feeds, etc. These dependencies introduce serious problems:
-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.
+- **Unstable**
+ External APIs can fail randomly due to bugs, maintenance, or release workflows. Your tests fail even when your code is correct.
+- **No Test Environment**
+ Many third-party APIs don't offer dedicated test environments, forcing you to test against production or skip testing entirely.
+- **Uncontrollable State**
+ It's often impossible to set up external systems in the exact state your test needs such as specific user data, edge cases, error conditions.
-
+These limitations make acceptance testing prone to errors and unreliable. Tests that should actually verify the behavior
+of your system instead become tests of whether external APIs happen to be working today.
-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.
+> Your acceptance tests shouldn't fail because a third-party API is down.
+> They should validate your system's behavior under controlled conditions.
-### Acceptance Testing Across Boundaries
+## How Mokapi Solves This
-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.
+Mokapi lets you simulate realistic API behavior in a way that's fast, accurate, and under your full control.
+It acts as a stand-in for external APIs during testing, allowing you to focus on validating your system's
+behavior instead of fighting with unstable dependencies.
-
+
-### Powerful Flexibility for Real-World Scenarios
+### Flexible Testing Boundaries
-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.
+Mokapi simplifies acceptance testing across flexible system boundaries, whether you are focusing on a single
+microservice or validating your entire architecture by mocking the APIs they depend on.
-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
+You decide where to draw the boundary. Test a single microservice by mocking everything it calls, or test an
+entire subsystem by mocking only the external APIs at the edges. Mokapi adapts to your testing strategy.
-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.
+### What Mokapi Brings to Acceptance Testing
-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.
+- **Realistic Scenarios:**
+ JavaScript-based handlers let you simulate edge cases, error conditions, and complex workflows that are hard or impossible to trigger with real APIs
+- **Specification-Driven Validation:**
+ Mocks are continuously validated against OpenAPI or AsyncAPI specs, ensuring they accurately reflect the APIs being simulated
+- **Smart Patching:**
+ Override only the data relevant to your test without redefining entire responses, keeping tests focused and maintainable
+- **Version Management:**
+ Update API specifications as providers release new versions; Mokapi catches incompatibilities before production
+- **Complete Control:**
+ Set up exact states, trigger errors, simulate timeouts, and make everything programmable and repeatable.
-#### Smart Mock Customization with Patch Mechanism
+### Example: Smart Mock Customization - Focus on What Matters
-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.
+With Mokapi, you can generate valid mock data from your OpenAPI specification and customize
+only the parts that matter for your test.
-Here's an example:
+In this example, the mock response is generated automatically, and you override just a single field:
```typescript
-import { on, patch } from 'mokapi';
+import { on } 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' });
+ response.data.name = 'Odie';
- // Alternatively, patch Mokapi's autogenerated response and just set the name
+ // Alternatively, use Object.assign-style patching
// 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.
+This approach gives you:
+- **Schema compliance:** The generated data matches your OpenAPI specification
+- **Test focus:** Override only what matters for this specific test (the pet's name)
+- **Maintainability:** When the schema changes, only failing patches need updates, not entire mock responses
-### Making Acceptance Testing Sustainable
+### Early Warning System for API Changes
-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.
+When a provider releases a new API version, update the specification in Mokapi. If your mock data or test
+calls no longer conform to the updated spec, Mokapi returns validation errors that your acceptance tests
+catch immediately.
-Mokapi doesn’t just enable acceptance testing—it makes it **practical, maintainable, and deeply aligned with your evolving system and its requirements**.
+This becomes an automated API version compatibility check, catching breaking changes before they reach production.
-## Ready to get started?
+## Making Acceptance Testing Sustainable
-Learn how to set up acceptance tests with Mokapi in your CI/CD pipeline:
+By combining flexible mocks, specification validation, and smart patching, **Mokapi makes acceptance
+testing more resilient, focused, and maintainable**.
-👉 [Running Mokapi in a CI/CD Pipeline](/resources/tutorials/running-mokapi-in-a-ci-cd-pipeline)
+Your tests answer the right question: "Does our system behave correctly?", without getting derailed by
+external API instability, missing test environments, or uncontrollable state.
----
+Mokapi doesn't just enable acceptance testing. It makes it **practical, maintainable, and deeply aligned
+with your evolving system and its requirements**.
+
+## Ready to Build Better Acceptance Tests?
+
+Learn how to integrate Mokapi into your CI/CD pipeline and start testing with confidence.
-*This article is also available on [LinkedIn](https://www.linkedin.com/pulse/acceptance-testing-mokapi-focus-what-matters-marcel-lehmann-fccjf)*
+{{ cta-grid key="links" }}
----
\ No newline at end of file
diff --git a/docs/resources/blogs/automation-testing-agile-development.md b/docs/resources/blogs/automation-testing-agile-development.md
index e4f38752b..1ea91b2f2 100644
--- a/docs/resources/blogs/automation-testing-agile-development.md
+++ b/docs/resources/blogs/automation-testing-agile-development.md
@@ -1,98 +1,209 @@
---
title: Automation Testing in Agile Development
description: Automated tests are key for Agile and CI teams. Discover how Mokapi enables faster, high-quality software development with mocking and testing tools.
+subtitle: Discover how automated testing with API mocking enables agile teams to iterate faster, maintain quality, and ship confidently, even with 50+ deployments per day.
+tags: [Agile, Testing]
+cards:
+ items:
+ - title: Get Started With Mokapi
+ href: /docs/get-started/running
+ description: Learn how to quickly set up and run your first mock REST API and view the results in the Mokapi dashboard.
+ - title: Acceptance Testing
+ href: /resources/blogs/acceptance-testing
+ description: Discover how Mokapi simplifies acceptance testing
+ - title: Record & Replay Real Traffic
+ href: /resources/blogs/record-and-replay-api-interactions
+ description: Capture real-world API traffic for testing, debugging, and offline development
+ - title: CI/CD Integration
+ href: /resources/tutorials/running-mokapi-in-a-ci-cd-pipeline
+ description: Learn how to use Mokapi in CI/CD pipelines to mock APIs and automate tests
+ - title: Programmable Scenarios
+ href: /resources/blogs/bring-your-mock-apis-to-life-with-javascript
+ description: Mokapi Scripts let you create dynamic, intelligent mock APIs that react to real request data, powered by plain JavaScript.
---
-# Automation Testing in Agile Development
+# Automation Testing in Agile: Test Faster, Ship Smarter
-Automation testing is a critical enabler of agile development, empowering teams
-to iterate faster, maintain high-quality standards, and deliver value to users
-in shorter timeframes. Mock tools like **Mokapi** amplify these benefits by helping
-teams communicate expectations effectively, decouple dependencies, and identify
-defects earlier in the development lifecycle. This combination not only streamlines
-workflows but also improves time to market.
+Agile development thrives on speed and iteration. Teams release smaller increments of code more frequently,
+respond to feedback faster, and deliver value to users in shorter cycles. But this velocity creates a critical
+challenge: *how do you maintain quality when deploying 10, 20, or even 50 times per day?*
-## The Need for Automated Testing in Agile Development
+The answer is automation testing and specifically, **automated testing with intelligent API mocking**.
+Without it, agile becomes unsustainable.
-In an agile development process, software systems are continuously evolving. New
-features are added, and changes are made in short iterations. Without an automated
-testing framework, maintaining the quality of a product becomes a daunting task.
-Automated tests ensure that the software remains flexible and easy to change, even
-as its complexity grows.
+## Why Manual Testing Fails in Agile
-### The Challenges of Manual Testing
+Manual testing might work for early-stage development, but it quickly becomes a bottleneck as projects scale
+and release cadence accelerates. Here's why:
-Manual testing may work for early-stage development but quickly becomes a
-bottleneck as projects scale. Agile teams aim to deliver smaller increments of
-code, release updates more often, and deploy new features frequently — sometimes
-as often as 50 production changes per day. Manual testing cannot keep up with this
-pace. It doesn't scale and is incompatible with the demands of continuous delivery.
+- **Doesn't Scale:**
+ As your codebase grows and features multiply, manual testing becomes exponentially slower and more expensive.
+- **Can't Keep Pace:**
+ Agile teams deploy multiple times per day. Manual testers can't validate every change before it ships.
+- **Human Error:**
+ Manual tests are inconsistent. Testers miss edge cases, skip steps under pressure, or introduce variability in results.
+- **Blocks Innovation:**
+ Teams become afraid to change code when they know it requires hours of manual regression testing.
-### Continuous Testing for Continuous Delivery
-
-To support continuous delivery, we need continuous testing. Automated tests ensure
-that each code increment is thoroughly validated before reaching production,
-eliminating the risk of introducing bugs to end users. This proactive approach
-transforms the fear of change into confidence, allowing teams to innovate without
-hesitation.
+In agile environments, manual testing transforms from a quality assurance process into a **delivery blocker**.
+The very thing meant to ensure quality ends up slowing down the feedback loop and frustrating developers.
> Write tests until fear is transformed into boredom
> Kent Beck
-## Why Contract Testing Matters
-
-Modern software systems are more complex than ever, often integrating with multiple
-external services maintained by other teams. Testing these integrations presents
-unique challenges. External systems may change unexpectedly, introduce bugs, or
-even be unavailable during testing, making end-to-end testing unreliable and
-time-consuming.
-
-### The Role of Contract Testing
+## The Agile Testing Mandate: Continuous Testing for Continuous Delivery
+
+To support continuous delivery, we need continuous testing. Every code change must be automatically
+validated before reaching production. This isn't optional, it's the only way to maintain quality at agile velocity.
+
+Automated tests provide:
+
+``` box=benefits title=Speed emoji=⚡
+Tests run in seconds or minutes, not hours or days. Feedback is immediate, enabling rapid iteration.
+```
+
+``` box=benefits title=Repeatability emoji=🔁
+Tests produce consistent results every time. No human variability, no forgotten steps.
+```
+
+``` box=benefits title=Confidence emoji=🛡️
+Teams deploy without fear, knowing tests catch regressions before production.
+```
+
+``` box=benefits title=Scalability emoji=📈
+Test suites grow with your codebase, covering more scenarios without additional manual effort.
+```
+
+This proactive approach transforms the *fear of change* into *confidence in quality*.
+Teams innovate freely, knowing their test suite acts as a safety net.
+
+## The Integration Testing Problem
+
+Modern software systems are rarely standalone. They integrate with payment providers, authentication
+services, notification systems, data warehouses, third-party APIs, and internal microservices.
+Testing these integrations presents unique challenges:
+
+
+
+
+
+
Challenge
+
Impact on Testing
+
Solved by Mocking?
+
+
+
+
+
External APIs can be down
+
Tests fail even when your code is correct
+
✓
+
+
+
No test environments provided
+
Forced to test against production or skip testing
+
✓
+
+
+
Uncontrollable external state
+
Can't set up specific test scenarios
+
✓
+
+
+
Slow external responses
+
Test suite takes hours to complete
+
✓
+
+
+
External APIs change unexpectedly
+
Breaking changes caught in production
+
✓
+
+
+
+
-Contract testing solves this problem by focusing solely on the system you are
-responsible for. Instead of testing the entire ecosystem, you simulate interactions
-with external systems, allowing you to verify that your system adheres to the
-agreed-upon contracts with its dependencies.
+End-to-end testing against real external systems is **unreliable, slow, and often impossible**.
+This is where contract testing and API mocking become essential.
-Key Benefits of Contract Testing:
+### Contract Testing: Focus on What You Control
-- Isolation: Test your system independently of external dependencies.
-- Speed: Avoid delays caused by dependency availability or state management.
-- Resilience: Eliminate runtime failures caused by changes in external systems.
+Contract testing solves this by focusing solely on the system you're responsible for.
+Instead of testing the entire ecosystem, you:
-## How Mokapi Supports Agile Testing
+- **Simulate external systems** using their published contracts (OpenAPI, AsyncAPI)
+- **Verify your system adheres to contracts** when calling external APIs
+- **Test independently** without waiting for external services to be available
+- **Control the test environment** completely, enabling reproducible tests for edge cases and error conditions
-Mokapi makes it easy to simulate external systems, such as REST APIs or
-Apache Kafka topics, enabling controlled and reliable tests. With Mokapi, you
-can decouple your testing from external services, reducing complexity and
-increasing the efficiency of your test suite.
+*You test what you own. You mock what you don't.*
-### End-to-End Testing with Mock Tools
+## How Mokapi Enables Agile Testing
-To create stable tests, all interactions with external systems must be simulated.
-By using Mokapi, you can:
+Mokapi makes contract testing and API mocking practical for agile teams. It provides the speed,
+flexibility, and specification-driven validation needed to test confidently at high velocity.
-- Simulate APIs and message queues like Kafka.
-- Customize responses to reflect real-world scenarios.
-- Focus testing efforts on your system under test (SUT), rather than the entire system.
+What Mokapi Brings to Your Test Suite:
-## The Impact of Automated Testing with Mock Tools
+``` box=feature title="Mock Any API or Message Queue" emoji=🎭
+Simulate REST APIs, GraphQL, Kafka topics, and more using OpenAPI and AsyncAPI specifications. Your tests interact with realistic mock services instead of brittle test doubles.
+```
-By using tools like Mokapi into your testing strategy can dramatically improve your team’s
-efficiency and product quality:
+``` box=feature title="Fast, Isolated Tests" emoji=⚡
+No network calls to external services means tests run in milliseconds, not seconds or minutes. Your CI pipeline completes faster, giving developers immediate feedback.
+```
+
+``` box=feature title="Specification-Driven Validation" emoji=🎯
+Mokapi validates all requests and responses against your OpenAPI/AsyncAPI specs. Catch contract violations before they reach production.
+```
+
+``` box=feature title="Programmable Scenarios" emoji=🔧
+Use JavaScript to simulate edge cases, timeouts, error conditions, and complex workflows that are hard or impossible to trigger with real APIs.
+```
+
+``` box=feature title="Record & Replay Real Traffic" emoji=🔄
+Capture real API interactions from staging or production, then replay them in tests. Build test suites from actual user behavior.
+```
+
+``` box=feature title="CI/CD Integration" emoji=🚀
+Run Mokapi in Docker, Kubernetes, or GitHub Actions. It fits seamlessly into existing CI/CD pipelines without infrastructure changes.
+```
+
+## Example: Testing a Payment Integration
+
+Imagine testing a checkout flow that integrates with Stripe. Without mocking:
+
+- You need test API keys and a Stripe test account
+- Tests can fail if Stripe's API is down or slow
+- You can't easily simulate declined cards, timeouts, or rate limits
+- Tests are slow due to network round trips
+
+**With Mokapi:**
+
+- Define Stripe's API contract using their OpenAPI spec
+- Mock successful charges, declined cards, and error responses programmatically
+- Tests run in milliseconds with no external dependencies
+- Simulate edge cases that would be impossible to trigger with the real API
+
+*Your tests focus on your checkout logic, not on whether Stripe is working today.*
+
+## From Fear to Confidence
+
+Automation testing isn't optional in agile development, it's the foundation that makes continuous delivery
+possible. Without it, teams slow down, quality suffers, and deployments become risky events instead
+of routine operations.
+
+Tools like Mokapi take this further by solving the integration testing problem. By mocking external
+dependencies, validating contracts, and enabling fast, isolated tests, Mokapi empowers teams to:
-- **Speed:** Identify and resolve defects faster, reducing overall testing time.
-- **Accuracy:** Gain more reliable test results by simulating controlled environments.
-- **Efficiency:** Streamline testing processes, allowing your team to focus on core development tasks.
-- **Quality:** Deliver higher-quality software to users faster and with greater confidence.
+- Test faster without sacrificing coverage
+- Deploy confidently knowing tests catch regressions
+- Simulate scenarios impossible to reproduce with real APIs
+- Maintain quality even as system complexity grows
-## Conclusion
+Whether you're building REST APIs, event-driven architectures, or complex microservices, *Mokapi
+equips your team to test better, faster, and smarter*.
-Automation testing is no longer optional in the world of agile development. It is
-a necessity that ensures teams can adapt to change, innovate quickly, and deliver
-value to users consistently. Tools like Mokapi take this a step further by enabling
-seamless integration testing through mocking and contract testing, empowering teams
-to maintain quality even in the face of complexity.
+## Ready to Transform Your Testing?
-Whether you're developing REST APIs, event-driven architectures, or complex microservices, Mokapi equips your team with the tools to test better, faster, and smarter.
+See how Mokapi enables fast, reliable automated testing for agile teams shipping multiple times per day.
-Start transforming your testing process with Mokapi today!
+{{ card-grid key="cards" }}
\ No newline at end of file
diff --git a/docs/resources/blogs/end-to-end-testing-mocked-apis.md b/docs/resources/blogs/end-to-end-testing-mocked-apis.md
index 9d5b6b993..4aefbf375 100644
--- a/docs/resources/blogs/end-to-end-testing-mocked-apis.md
+++ b/docs/resources/blogs/end-to-end-testing-mocked-apis.md
@@ -139,12 +139,12 @@ export default () => {
break;
}
}
- })
+ }, { track: true })
on('http', (request, response) => {
if (!delay) {
sleep(delay);
}
- }, { track: true } )
+ }, { track: () => delay !== undefined } )
}
```
diff --git a/docs/resources/blogs/ensuring-api-contract-compliance-with-mokapi.md b/docs/resources/blogs/ensuring-api-contract-compliance-with-mokapi.md
index bf7e07aa3..3536aef57 100644
--- a/docs/resources/blogs/ensuring-api-contract-compliance-with-mokapi.md
+++ b/docs/resources/blogs/ensuring-api-contract-compliance-with-mokapi.md
@@ -1,63 +1,77 @@
---
-title: Ensure API Contract Compliance with Mokapi Validation
-description: Validate HTTP API requests and responses with Mokapi to catch breaking changes early and keep backend implementations aligned with your OpenAPI spec.
+title: "Guard Your API Contracts: Catch Breaking Changes Before Production"
+description: Stop API drift in its tracks. Use Mokapi as a validation layer to enforce OpenAPI contracts between clients and backends
+subtitle: Stop API drift in its tracks. Use Mokapi as a validation layer to enforce OpenAPI contracts between clients and backends, no matter who's calling or what they're building.
image:
url: /mokapi-using-as-proxy.png
alt: Flow diagram illustrating how Mokapi enforces OpenAPI contracts between clients, Playwright tests, and backend APIs.
tech: http
+links:
+ items:
+ - title: Get Started with Mokapi
+ href: /docs/get-started/installation
+ - title: Record & Replay API Traffic
+ href: /resources/blogs/record-and-replay-api-interactions
---
-# Ensuring Compliance with the HTTP API Contract Using Mokapi for Request Forwarding and Validation
+# Guard Your API Contracts: Catch Breaking Changes Before Production
-In modern distributed systems, APIs are everywhere — frontend-to-backend,
-backend-to-backend, microservices communicating internally, mobile apps, test
-automation tools, and more. Each interaction relies on a shared API contract,
-often expressed through an OpenAPI specification. Even small
-deviations can introduce bugs, break integrations, or slow down development.
+In modern distributed systems, APIs are everywhere, frontend to backend, service
+to service, mobile apps, test automation, third-party integrations. Each interaction
+relies on a shared API contract, typically expressed through an OpenAPI specification.
+But what happens when that contract drifts?
-By placing Mokapi between a client and a backend, you can ensure that every
-**request and response adheres to your OpenAPI specification**. With a few lines
-of JavaScript, Mokapi can forward requests to your backend while validating both
-sides of the interaction. This provides a powerful way to enforce API correctness —
-whether the client is a browser, Playwright tests, your mobile app, or even
-another backend service.
+A renamed field breaks the mobile app. A missing validation lets bad data into production.
+An unexpected status code crashes the frontend. Small deviations compound into debugging
+nightmares, broken integrations, and slowed development velocity.
-In this article, I explore how Mokapi can act as **a contract-enforcing validation layer**
-and why this approach benefits frontend developers, backend teams, QA engineers,
-and platform engineers alike.
+> What if every API interaction was automatically validated against your OpenAPI spec?
+> That's exactly what Mokapi enables, a lightweight validation layer that sits between
+> client and backend, enforcing contract compliance on both sides of every request.
-
+## The Problem: API Drift is Inevitable
-## How to Use Mokapi for API Validation with Request Forwarding?
+Even with the best intentions, API contracts drift from reality:
-Mokapi cannot only be used for mocking APIs, but it can also sit between any
-consumer and a backend service to validate real traffic. Using a small
-JavaScript script, Mokapi can forward requests to your backend and
-validates both requests and responses.
+- **Backend changes without updating the spec:** A developer renames a field, changes a response structure, or adds a new required parameter, but forgets to update the OpenAPI documentation.
+- **Frontend assumes behavior that was never specified:** A client sends malformed requests or expects fields that don't exist, and the backend silently accepts it (for now).
+- **Microservices evolve independently:** Service A updates its contract, but Service B keeps calling the old version. Everything works until it doesn't.
+- **Tests pass, but production breaks:** E2E tests mock the API instead of hitting the real backend, masking contract violations until deployment.
+
+The result? Teams spend hours debugging "why is this suddenly broken?" instead of shipping features.
+
+## The Solution: Mokapi as a Contract Guardian
+
+Mokapi can sit between any client and backend to validate every request and response against your OpenAPI specification.
+With a simple JavaScript forwarding script, Mokapi becomes a transparent validation layer that:
+
+- Blocks invalid requests before they reach your backend
+- Validates backend responses before they reach the client
+- Provides clear, actionable error messages when violations occur
+- Works with browsers, test frameworks, mobile apps, and service-to-service traffic
+
+
+
+## How It Works: Request Forwarding with Validation
+
+The core concept is simple: Mokapi intercepts HTTP traffic, validates it against your OpenAPI spec,
+forwards valid requests to the backend, validates the response, and only then returns it to the client.
+
+Here's the complete forwarding and validation script:
```typescript
import { on } from 'mokapi';
import { fetch } from 'mokapi/http';
/**
- * This script demonstrates how to forward incoming HTTP requests
- * to a real backend while letting Mokapi validate responses according
- * to your OpenAPI spec.
- *
- * The script listens to all HTTP requests and forwards them based
- * on the `request.api` field. Responses from the backend are
- * validated when possible, and any errors are reported back to
- * the client.
+ * Forward incoming requests to backend services while validating
+ * both requests and responses against OpenAPI specifications.
*/
export default async function () {
-
- /**
- * Register a global HTTP event handler.
- * This function is called for every incoming request.
- */
+
on('http', async (request, response) => {
- // Determine the backend URL to forward this request to
+ // Map request to backend URL based on OpenAPI spec name
const url = getForwardUrl(request)
// If no URL could be determined, return an error immediately
@@ -76,7 +90,7 @@ export default async function () {
timeout: '30s'
});
- // Copy status code and headers from the backend response
+ // Copy status code and headers
response.statusCode = res.statusCode;
response.headers = res.headers
@@ -121,146 +135,108 @@ export default async function () {
}
```
-For each interaction, Mokapi performs four important steps:
-
-### 1. Validates incoming requests
-
-Mokapi checks every incoming request against your OpenAPI specification:
-
-- HTTP method
-- URL & parameters
-- headers
-- request body
-
-If the client sends anything invalid, Mokapi blocks it and returns a clear
-validation error.
-
-### 2. Forwards valid requests to your backend
+### The Four-Step Validation Flow
-If the request is valid, Mokapi forwards it unchanged to the backend using JavaScript.
+#### Validate Incoming Request
-- No changes are required in your backend.
-- No additional infrastructure is necessary.
+Mokapi checks the HTTP method, URL parameters, headers, and request body against your OpenAPI spec.
+Invalid requests are blocked with clear error messages.
-### 3. Validates backend responses
+#### Forward Valid Requests
-Once the backend responds, Mokapi validates the response against the OpenAPI specification:
+Only requests that pass validation are forwarded to the backend. No changes to your backend code
+or infrastructure are required.
-- status codes
-- headers
-- response body
+#### Validate Backend Response
-If something doesn't match the contract, Mokapi blocks it and sends a validation error back to the client.
+Mokapi validates the backend's response, status codes, headers, and response body against the OpenAPI specification.
-### 4. Return the validated response to the client
+#### Return Validated Response
-Only responses that pass validation reach the client, guaranteeing contract fidelity end-to-end.
+Only responses that match the contract reach the client, guaranteeing end-to-end contract fidelity across every interaction.
-## Where You Can Use Mokapi for Request Forwarding and Validation
+## Where to Use Mokapi for Contract Validation
-Mokapi’s forwarding and validation capabilities make it useful far beyond local development or Playwright scripting.
+Mokapi's forwarding and validation capabilities work in multiple scenarios across your architecture:
-### Between Frontend and Backend
+### Frontend ↔ Backend
-Placing Mokapi between your frontend and backend ensures:
-- automatic request and response validation
-- immediate detection of breaking changes
-- backend and API specification evolve together
-- fewer “why is the frontend broken?” debugging loops
+Place Mokapi between your frontend and backend to catch contract violations during development:
+- Automatic request and response validation
+- Immediate detection of breaking changes
+- Backend and OpenAPI spec evolve together
+- Fewer "why is the frontend broken?" debugging loops
-Frontend developers can experiment with confidence, knowing the backend
-cannot silently diverge from the published contract.
+### Service ↔ Service
-### Between Backend Services (Service-to-Service)
+In microservice architectures, API drift between services causes instability. Mokapi provides:
+- Strict contract enforcement between services
+- Early detection of incompatible changes
+- Stable integrations as teams evolve independently
+- Clear validation errors during development and CI
-In microservice architectures, API drift between services is a frequent cause of instability.
-Routing service-to-service traffic through Mokapi gives you:
-- strict contract enforcement between services
-- early detection of incompatible changes
-- stable integrations even as teams evolve independently
-- clear validation errors during development and CI
+### Playwright Tests ↔ Backend
-Mokapi becomes a lightweight, spec-driven contract guardian across your backend ecosystem.
+One of the most powerful setups: Playwright → Mokapi → Backend
+- CI fails immediately when backend breaks the contract
+- Tests interact with real backend, not mocks
+- Validation errors are clear and actionable
+- Tests stay simpler, no manual validation needed
-### In Automated Testing (e.g., Playwright)
+### Kubernetes Test Environments
-This is one of the most powerful setups.
+Deploy Mokapi as a sidecar or standalone validation layer in preview environments:
+- Consistent contract validation for cluster traffic
+- Early detection before staging deployment
+- No modifications to backend services
+- Integrates with Helm charts and GitOps workflows
- Playwright → Mokapi → Backend
+## Why Teams Choose This Approach
-Benefits:
-- CI fails immediately when the backend breaks the API contract
-- tests interact with the real backend, not mocks
-- validation errors are clear and actionable
-- tests remain simpler — no need to validate everything in Playwright
-
-Your tests are guaranteed to hit a backend that actually matches the API contract.
-
-### In Kubernetes Test Environments
-
-Mokapi can also be used in temporary or preview environments to ensure contract validation across the entire cluster.
-
-In Kubernetes, Mokapi can be deployed as:
-- a sidecar container
-- a standalone validation layer in front of backend services
-- a temporary component inside preview environments
-
-This brings:
-- consistent contract validation for all cluster traffic
-- early detection of breaking API changes before staging
-- contract enforcement without modifying backend services
-- transparent operation — apps talk to Mokapi, Mokapi talks to the backend
-
-You can integrate Mokapi into Helm charts, GitOps workflows, or test namespaces.
-
-## Why Teams Benefit from Using Mokapi Between Client and Backend
-
-### Automatic Contract Enforcement
-
-Every interaction is validated against your OpenAPI specification. Your backend can no longer quietly drift from the contract.
+``` box=feature title="Automatic Contract Enforcement"
+Every interaction is validated against your OpenAPI spec. Your backend can no longer silently drift from the contract.
+```
-### Immediate Detection of Breaking Changes
+``` box=feature title="Immediate Detection of Breaking Change"
+Issues are caught early, renamed fields, wrong formats, unexpected status codes, mismatched data types before they reach production.
+```
-Issues are caught early, not just in staging or production, such as:
- - renamed or missing fields
- - wrong or inconsistent formats
- - unexpected status codes
- - mismatched data types
+``` box=feature title="More Reliable Frontend Development"
+Frontend teams get consistent, validated API responses with fewer sudden breaking changes and a smoother development workflow.
+```
-### More Reliable Frontend Development
+``` box=feature title="Better Cross-Team Collaboration"
+Backend developers instantly see contract violations. Frontend engineers get stable APIs. QA gets reliable test environments. Platform teams reduce deployment risk.
+```
-Frontend teams get:
-- consistent, validated API responses
-- fewer sudden breaking changes
-- a smoother development workflow
+``` box=feature title="Smooth Mock-to-Real Transition"
+Start with mocked endpoints in early development. Later, simply forward requests to the real backend while keeping validation in place.
+```
-This reduces context-switching and debugging time.
+``` box=feature title="Actionable Error Messages"
+When validation fails, Mokapi provides clear, detailed error messages showing exactly what doesn't match the spec and why.
+```
-### Better Collaboration Between Teams
+> "Mokapi becomes your always-on API contract guardian, lightweight, transparent, and spec-driven."
-With Mokapi validating both sides:
-- backend developers instantly see when they violate the contract
-- frontend engineers get stable, predictable APIs
-- QA gets reliable test environments
-- platform engineers reduce risk during deployments
+## Getting Started
-Mokapi becomes a shared API contract watchdog across the organization.
+Implementing Mokapi as a validation layer is straightforward:
-### Smooth Transition from Mocks to Real Systems
+1. **Define your OpenAPI specification** for the API you want to validate
+2. **Create a forwarding script** using the example above, mapping `request.api` to your backend URLs
+3. **Run Mokapi** between your client and backend (locally, in Docker, or in Kubernetes)
+4. **Point your client** at Mokapi instead of directly at the backend
+5. **Watch validation errors surface** in real-time as you develop, test, and deploy
-Teams often start with mocked endpoints in early development. Later, they can simply begin forwarding requests to the
-real backend—while keeping validation in place.
+No changes to your backend code. No infrastructure overhaul. Just a transparent validation layer
+that enforces your API contract at runtime.
-## Conclusion
+## Stop API Drift. Start Enforcing Contracts.
-Using Mokapi between frontend and backend, between backend services, or inside Kubernetes environments provides:
-- strong contract enforcement
-- automatic validation for every interaction
-- early detection of breaking changes
-- stable multi-team integration
-- more reliable CI pipelines
-- a smooth path from mocking to real backend validation
+With Mokapi as a validation layer, you get automatic contract enforcement, early detection of breaking
+changes, and stable multi-team integration, all without touching your backend code.
-Mokapi ensures your API stays aligned with its specification, no matter how quickly your system evolves.
+{{ cta-grid key="links" }}
-> *Mokapi becomes your always-on API contract guardian — lightweight, transparent, and spec-driven.*
\ No newline at end of file
+
Ready to guard your API contracts? Start validating today.
\ No newline at end of file
diff --git a/docs/resources/blogs/record-and-replay-api-interactions.md b/docs/resources/blogs/record-and-replay-api-interactions.md
index 137efb217..f3367dbd2 100644
--- a/docs/resources/blogs/record-and-replay-api-interactions.md
+++ b/docs/resources/blogs/record-and-replay-api-interactions.md
@@ -1,14 +1,14 @@
---
title: "Record & Replay: API Interactions with Mokapi"
-description: Capture real-world API traffic for testing, debugging, and offline development—all with a simple JavaScript script
-subtitle: Capture real-world API traffic for testing, debugging, and offline development—all with a simple JavaScript script
+description: Capture real-world API traffic for testing, debugging, and offline development, all with a simple JavaScript script
+subtitle: Capture real-world API traffic for testing, debugging, and offline development, all with a simple JavaScript script
tech: http
tags: ['HTTP']
---
# Record & Replay: API Interactions with Mokapi
-In a [previous article](ensuring-api-contract-compliance-with-mokapi.md), we explored how Mokapi can act as an API
+In a [previous article](/resources/blogs/guard-your-api-contracts), we explored how Mokapi can act as an API
specification guard between services—validating requests and responses against your OpenAPI specs in real-time.
But Mokapi's capabilities go far beyond validation. In this article, we'll dive into another powerful use case:
recording and replaying API interactions.
diff --git a/docs/resources/tutorials/simple-http-api.md b/docs/resources/tutorials/simple-http-api.md
index 60013531e..b78b53cc2 100644
--- a/docs/resources/tutorials/simple-http-api.md
+++ b/docs/resources/tutorials/simple-http-api.md
@@ -4,6 +4,7 @@ description: Learn how to mock a REST API using an OpenAPI specification with Mo
subtitle: Learn how to mock a REST API using an OpenAPI specification with Mokapi. This tutorial covers basic setup, configuration, and Docker deployment.
icon: bi-globe
tech: http
+tags: [HTTP, OpenAPI]
cards:
items:
- title: Dynamic Responses
@@ -15,8 +16,8 @@ cards:
- title: CI/CD Integration
href: /resources/blogs/end-to-end-testing-with-mocked-apis
description: Run Mokapi in GitHub Actions for automated testing workflows
-
---
+
# Get started with REST API
In this tutorial, you will:
diff --git a/docs/resources/tutorials/simple-kafka-api.md b/docs/resources/tutorials/simple-kafka-api.md
index bb29c9d95..9b35f585d 100644
--- a/docs/resources/tutorials/simple-kafka-api.md
+++ b/docs/resources/tutorials/simple-kafka-api.md
@@ -1,19 +1,47 @@
---
title: Get started with Kafka
description: Learn how to mock a Kafka Topic and verify that your producer generates valid messages according your AsyncAPI specification.
+subtitle: Learn how to mock a Kafka topic using AsyncAPI specifications with Mokapi. Validate producer messages and test consumers without requiring a live Kafka cluster.
+tags: [Kafka, AsyncAPI]
icon: bi-lightning
tech: kafka
+cards:
+ items:
+ - title: Testing Kafka Workflows with Playwright and Mokapi
+ href: /resources/blogs/testing-kafka-workflows-playwright
+ description: Simulating real message flows end-to-end with Node.js, Kafka topics, and browser-driven tests.
---
# Get started with Kafka
-This tutorial provides a step-by-step guide to mocking a Kafka topic using Mokapi
-and verifying that a producer generates valid messages based on an AsyncAPI specification.
-This approach enables the simulation of Kafka environments without requiring a live Kafka cluster.
+This tutorial provides a step-by-step guide to mocking a Kafka topic using Mokapi and verifying
+that a producer generates valid messages based on an AsyncAPI specification. This approach enables
+simulation of Kafka environments without requiring a live Kafka cluster.
+
+In this tutorial, you will:
+- Create an AsyncAPI specification defining a Kafka topic with schema validation
+- Configure and run Mokapi as a mock Kafka broker in Docker
+- Write a .NET producer that sends messages to the mocked topic
+- Verify message validation and monitoring using the Mokapi dashboard
+- Create a .NET consumer to read messages from the mocked topic
+
+``` box=tree title="Project Structure"
+📄 kafka.yaml
+📄 Dockerfile
+📁 Kafka.GetStarted (optional)
+ 📄 Consumer.cs
+ 📄 Kafka.GetStarted.csproj
+ 📄 Producer.cs
+ 📄 Program.cs
+```
-## Create AsyncAPI file
+``` box=info
+You can find the [full working example](https://github.com/marle3003/mokapi/tree/main/examples/kafka/get-started) in the examples.
+```
-Let's start by creating a file named `kafka.yml` with the following content.
+## Create AsyncAPI file
+
+Create a file named `kafka.yaml` that defines a Kafka topic with message validation:
```yaml
asyncapi: '2.0.0'
@@ -69,17 +97,21 @@ components:
- email
```
-This creates a Kafka topic `users` with two partitions. The content type of the message's payload
-is `application/json` and the object must have the properties `id`, `name` and `email`.
+### Specification Breakdown
+- **Topic:** Creates a `users` topic with 2 partitions
+- **Content Type:** Messages must be JSON (`application/json`)
+- **Schema:** Each message must have `id` (UUID), `name` (string), and `email` (string)
+- **Validation:** All three fields are required; missing fields will cause validation errors
+- **Key Type:** Message keys must be strings
-``` box=info
-When Mokapi receives an invalid message it will return the error `CORRUPT_MESSAGE`and logs an
-error, for instance `kafka: invalid message received for topic users: missing required field name...`
+``` box=info title="Message Validation"
+When Mokapi receives an invalid message, it will return the error CORRUPT_MESSAGE and log an error message
+like: kafka: invalid message received for topic users: missing required field name...
```
-## Create a Dockerfile
+## Create a Dockerfile
-Next create a `Dockerfile` to configure Mokapi to use the AsyncAPI specification file
+Create a `Dockerfile` to configure Mokapi with the AsyncAPI specification:
```dockerfile
FROM mokapi/mokapi:latest
@@ -89,17 +121,33 @@ COPY ./kafka.yaml /demo/
CMD ["--Providers.File.Directory=/demo"]
```
-## Start Mokapi
+### Dockerfile Breakdown
+- **Base Image:** Uses the official Mokapi Docker image
+- **Copy Specification:** Copies the AsyncAPI specification into the container
+- **Configuration:** Instructs Mokapi to load specifications from the `/demo` directory
-Now we can start our container and verify in Mokapi's Dashboard (http://localhost:8080) our mocked Kafka topic
+## Start Mokapi
+
+Build and run the Docker container, exposing the Kafka broker and dashboard ports:
```
docker run -p 9092:9092 -p 8080:8080 --rm -it $(docker build -q .)
```
-## Create a Kafka Producer
+This command:
+- **Builds** the Docker image from your Dockerfile
+- **Exposes port 9092** for the Kafka broker protocol
+- **Exposes port 8080** for the Mokapi dashboard
+- **Runs interactively** with automatic cleanup when stopped
+
+``` box=result title="Mokapi is Running"
+Open your browser and navigate to the Mokapi Dashboard at http://localhost:8080 to see your mocked Kafka
+topic. You can verify the topic configuration, view messages, and monitor producer/consumer activity.
+```
-You can now produce messages to the mocked Kafka topic. Below is an example using C#.
+## Create a Kafka Producer
+
+Now you can produce messages to the mocked Kafka topic. Below is an example using C# with the Confluent.Kafka library:
```csharp
public class Producer
@@ -128,21 +176,40 @@ public class Producer
}
```
-## Verifying Messages with Mokapi
+### Producer Code Breakdown
+
+- **Connection:** Connects to the Mokapi broker at `localhost:9092`
+- **Topic & Partition:** Targets the `users` topic, partition 1
+- **Message Key:** Uses `"alice"` as the message key (required by the AsyncAPI spec)
+- **Message Value:** Serializes a JSON object with `id`, `name`, and `email` fields
+- **JSON Format:** Uses camelCase naming to match the AsyncAPI schema
+
+``` box=info title="Schema Validation"
+Mokapi validates every message against the AsyncAPI schema. If you send a message missing the name field or
+with an invalid UUID format for id, Mokapi will reject it with a CORRUPT_MESSAGE error.
+```
+
+## Verifying Messages with Mokapi
-Mokapi provides a dashboard to monitor and verify messages sent to the mocked Kafka topics.
+Mokapi provides a comprehensive dashboard to monitor and verify messages sent to mocked Kafka topics.
-1.
Access the Mokapi Dashboard: Open your browser and navigate to http://localhost:8080/dashboard.
+### Dashboard Verification Steps
-2.
Navigate to the Kafka Section: In the dashboard, select the Kafka section to view the topics and messages.
+1. **Access the Mokapi Dashboard:** Open your browser and navigate to `http://localhost:8080/dashboard`
+2. **Navigate to the Kafka Section:** In the dashboard, select the Kafka section to view configured topics and their messages
+3. **Verify the Message:** Locate the `users` topic and verify that the message sent by your producer appears as expected. Mokapi displays the message key, value, partition, offset, and validation status
-3.
-## 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.
+In fast-paced development cycles, it's crucial to ensure your software meets real user expectations.
+Unit tests validate that individual components work correctly, but they can't answer the bigger question:
+*Does the system behave the way users expect?*
-### The Nature of Acceptance Tests
+That's where acceptance testing comes in, and it's more than just another layer of testing.
+It's a fundamental shift in how we think about software quality.
-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.
+> Is our software releasable?
-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.
+Among all testing levels, acceptance testing offers the most direct insight into whether software meets business and
+user expectations. It bridges the gap between user needs and code implementation by turning expectations into **precise**,
+**executable specifications** of system behavior.
-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.
+## What Makes Acceptance Tests Different
-### Solving Ambiguity and Ensuring Reproducibility
+### Unit Tests vs. Acceptance Tests
-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**.
+**Unit Tests:**
+- Focus on *how* components work internally
+- Test implementation details
+- Fast, isolated, developer-focused
+- Break when implementation changes
+- Answer: "Does this code work?"
-This is where acceptance testing shines.
+**Acceptance Tests:**
+- Focus on *what* the system does
+- Test behavior and outcomes
+- Slower, integrated, user-focused
+- Stable across implementation changes
+- Answer: "Does this system meet expectations?"
-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.
+### Acceptance Tests as Executable Specifications
-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
+At its core, an acceptance test is an *executable specification* of how a system should behave, written from a user's
+perspective. It's not concerned with implementation, only with behavior and outcomes.
-### A Contract of Trust
+When we get the abstraction level right, acceptance tests become **clear, precise, and maintainable**. They reflect
+scenarios that matter to users, expressed in a way that's both easy to read and easy to execute. They serve as
+living documentation that evolves with the system.
-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.
+### Removing Ambiguity, Ensuring Reproducibility
-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.
+One of the hardest challenges in software development isn't writing code, it's understanding the problem
+clearly and expressing it precisely. Software requires unambiguous clarity, unlike natural language which
+thrives on context and implication.
-### Making Software Releasable
+This is where acceptance testing shines:
-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**.
+``` box=benefits title="Removes Ambiguity" emoji=🎯
+By expressing requirements in executable form, tests define exactly what needs to happen, no vague documentation or
+human interpretation required.
+```
-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.
+``` box=benefits title="Ensures Reproducibility" emoji=🔁
+Tests run automatically, as often as needed, catching regressions early and providing consistent results across environments.
+```
-### The problem with acceptance testing and 3rd party APIs
+``` box=benefits title="Creates Shared Understanding" emoji=🤝
+Developers, testers, and stakeholders rely on concrete, shared definitions of behavior rather than assumptions.
+```
-- **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.
+``` box=benefits title="Serves as a Contract" emoji=📜
+When everyone agrees on specifications encoded in tests, there's no room for misinterpretation between business and development.
+```
-These limitations can make acceptance testing brittle and unreliable—unless you can simulate the external system reliably.
+## The Problem: External APIs Break Acceptance Tests
-## How Mokapi Supports Acceptance Testing
+Acceptance tests sound great in theory, but in practice they often depend on external APIs such as payment providers,
+authentication services, notification systems, data feeds, etc. These dependencies introduce serious problems:
-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.
+- **Unstable**
+ External APIs can fail randomly due to bugs, maintenance, or release workflows. Your tests fail even when your code is correct.
+- **No Test Environment**
+ Many third-party APIs don't offer dedicated test environments, forcing you to test against production or skip testing entirely.
+- **Uncontrollable State**
+ It's often impossible to set up external systems in the exact state your test needs such as specific user data, edge cases, error conditions.
-
+These limitations make acceptance testing prone to errors and unreliable. Tests that should actually verify the behavior
+of your system instead become tests of whether external APIs happen to be working today.
-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.
+> Your acceptance tests shouldn't fail because a third-party API is down.
+> They should validate your system's behavior under controlled conditions.
-### Acceptance Testing Across Boundaries
+## How Mokapi Solves This
-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.
+Mokapi lets you simulate realistic API behavior in a way that's fast, accurate, and under your full control.
+It acts as a stand-in for external APIs during testing, allowing you to focus on validating your system's
+behavior instead of fighting with unstable dependencies.
-
+
-### Powerful Flexibility for Real-World Scenarios
+### Flexible Testing Boundaries
-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.
+Mokapi simplifies acceptance testing across flexible system boundaries, whether you are focusing on a single
+microservice or validating your entire architecture by mocking the APIs they depend on.
-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
+You decide where to draw the boundary. Test a single microservice by mocking everything it calls, or test an
+entire subsystem by mocking only the external APIs at the edges. Mokapi adapts to your testing strategy.
-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.
+### What Mokapi Brings to Acceptance Testing
-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.
+- **Realistic Scenarios:**
+ JavaScript-based handlers let you simulate edge cases, error conditions, and complex workflows that are hard or impossible to trigger with real APIs
+- **Specification-Driven Validation:**
+ Mocks are continuously validated against OpenAPI or AsyncAPI specs, ensuring they accurately reflect the APIs being simulated
+- **Smart Patching:**
+ Override only the data relevant to your test without redefining entire responses, keeping tests focused and maintainable
+- **Version Management:**
+ Update API specifications as providers release new versions; Mokapi catches incompatibilities before production
+- **Complete Control:**
+ Set up exact states, trigger errors, simulate timeouts, and make everything programmable and repeatable.
-#### Smart Mock Customization with Patch Mechanism
+### Example: Smart Mock Customization - Focus on What Matters
-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.
+With Mokapi, you can generate valid mock data from your OpenAPI specification and customize
+only the parts that matter for your test.
-Here's an example:
+In this example, the mock response is generated automatically, and you override just a single field:
```typescript
-import { on, patch } from 'mokapi';
+import { on } 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' });
+ response.data.name = 'Odie';
- // Alternatively, patch Mokapi's autogenerated response and just set the name
+ // Alternatively, use Object.assign-style patching
// 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.
+This approach gives you:
+- **Schema compliance:** The generated data matches your OpenAPI specification
+- **Test focus:** Override only what matters for this specific test (the pet's name)
+- **Maintainability:** When the schema changes, only failing patches need updates, not entire mock responses
-### Making Acceptance Testing Sustainable
+### Early Warning System for API Changes
-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.
+When a provider releases a new API version, update the specification in Mokapi. If your mock data or test
+calls no longer conform to the updated spec, Mokapi returns validation errors that your acceptance tests
+catch immediately.
-Mokapi doesn’t just enable acceptance testing—it makes it **practical, maintainable, and deeply aligned with your evolving system and its requirements**.
+This becomes an automated API version compatibility check, catching breaking changes before they reach production.
-## Ready to get started?
+## Making Acceptance Testing Sustainable
-Learn how to set up acceptance tests with Mokapi in your CI/CD pipeline:
+By combining flexible mocks, specification validation, and smart patching, **Mokapi makes acceptance
+testing more resilient, focused, and maintainable**.
-👉 [Running Mokapi in a CI/CD Pipeline](/resources/tutorials/running-mokapi-in-a-ci-cd-pipeline)
+Your tests answer the right question: "Does our system behave correctly?", without getting derailed by
+external API instability, missing test environments, or uncontrollable state.
----
+Mokapi doesn't just enable acceptance testing. It makes it **practical, maintainable, and deeply aligned
+with your evolving system and its requirements**.
+
+## Ready to Build Better Acceptance Tests?
+
+Learn how to integrate Mokapi into your CI/CD pipeline and start testing with confidence.
-*This article is also available on [LinkedIn](https://www.linkedin.com/pulse/acceptance-testing-mokapi-focus-what-matters-marcel-lehmann-fccjf)*
+{{ cta-grid key="links" }}
----
\ No newline at end of file
diff --git a/docs/resources/blogs/automation-testing-agile-development.md b/docs/resources/blogs/automation-testing-agile-development.md
index e4f38752b..1ea91b2f2 100644
--- a/docs/resources/blogs/automation-testing-agile-development.md
+++ b/docs/resources/blogs/automation-testing-agile-development.md
@@ -1,98 +1,209 @@
---
title: Automation Testing in Agile Development
description: Automated tests are key for Agile and CI teams. Discover how Mokapi enables faster, high-quality software development with mocking and testing tools.
+subtitle: Discover how automated testing with API mocking enables agile teams to iterate faster, maintain quality, and ship confidently, even with 50+ deployments per day.
+tags: [Agile, Testing]
+cards:
+ items:
+ - title: Get Started With Mokapi
+ href: /docs/get-started/running
+ description: Learn how to quickly set up and run your first mock REST API and view the results in the Mokapi dashboard.
+ - title: Acceptance Testing
+ href: /resources/blogs/acceptance-testing
+ description: Discover how Mokapi simplifies acceptance testing
+ - title: Record & Replay Real Traffic
+ href: /resources/blogs/record-and-replay-api-interactions
+ description: Capture real-world API traffic for testing, debugging, and offline development
+ - title: CI/CD Integration
+ href: /resources/tutorials/running-mokapi-in-a-ci-cd-pipeline
+ description: Learn how to use Mokapi in CI/CD pipelines to mock APIs and automate tests
+ - title: Programmable Scenarios
+ href: /resources/blogs/bring-your-mock-apis-to-life-with-javascript
+ description: Mokapi Scripts let you create dynamic, intelligent mock APIs that react to real request data, powered by plain JavaScript.
---
-# Automation Testing in Agile Development
+# Automation Testing in Agile: Test Faster, Ship Smarter
-Automation testing is a critical enabler of agile development, empowering teams
-to iterate faster, maintain high-quality standards, and deliver value to users
-in shorter timeframes. Mock tools like **Mokapi** amplify these benefits by helping
-teams communicate expectations effectively, decouple dependencies, and identify
-defects earlier in the development lifecycle. This combination not only streamlines
-workflows but also improves time to market.
+Agile development thrives on speed and iteration. Teams release smaller increments of code more frequently,
+respond to feedback faster, and deliver value to users in shorter cycles. But this velocity creates a critical
+challenge: *how do you maintain quality when deploying 10, 20, or even 50 times per day?*
-## The Need for Automated Testing in Agile Development
+The answer is automation testing and specifically, **automated testing with intelligent API mocking**.
+Without it, agile becomes unsustainable.
-In an agile development process, software systems are continuously evolving. New
-features are added, and changes are made in short iterations. Without an automated
-testing framework, maintaining the quality of a product becomes a daunting task.
-Automated tests ensure that the software remains flexible and easy to change, even
-as its complexity grows.
+## Why Manual Testing Fails in Agile
-### The Challenges of Manual Testing
+Manual testing might work for early-stage development, but it quickly becomes a bottleneck as projects scale
+and release cadence accelerates. Here's why:
-Manual testing may work for early-stage development but quickly becomes a
-bottleneck as projects scale. Agile teams aim to deliver smaller increments of
-code, release updates more often, and deploy new features frequently — sometimes
-as often as 50 production changes per day. Manual testing cannot keep up with this
-pace. It doesn't scale and is incompatible with the demands of continuous delivery.
+- **Doesn't Scale:**
+ As your codebase grows and features multiply, manual testing becomes exponentially slower and more expensive.
+- **Can't Keep Pace:**
+ Agile teams deploy multiple times per day. Manual testers can't validate every change before it ships.
+- **Human Error:**
+ Manual tests are inconsistent. Testers miss edge cases, skip steps under pressure, or introduce variability in results.
+- **Blocks Innovation:**
+ Teams become afraid to change code when they know it requires hours of manual regression testing.
-### Continuous Testing for Continuous Delivery
-
-To support continuous delivery, we need continuous testing. Automated tests ensure
-that each code increment is thoroughly validated before reaching production,
-eliminating the risk of introducing bugs to end users. This proactive approach
-transforms the fear of change into confidence, allowing teams to innovate without
-hesitation.
+In agile environments, manual testing transforms from a quality assurance process into a **delivery blocker**.
+The very thing meant to ensure quality ends up slowing down the feedback loop and frustrating developers.
> Write tests until fear is transformed into boredom
> 
+## The Problem: API Drift is Inevitable
-## How to Use Mokapi for API Validation with Request Forwarding?
+Even with the best intentions, API contracts drift from reality:
-Mokapi cannot only be used for mocking APIs, but it can also sit between any
-consumer and a backend service to validate real traffic. Using a small
-JavaScript script, Mokapi can forward requests to your backend and
-validates both requests and responses.
+- **Backend changes without updating the spec:** A developer renames a field, changes a response structure, or adds a new required parameter, but forgets to update the OpenAPI documentation.
+- **Frontend assumes behavior that was never specified:** A client sends malformed requests or expects fields that don't exist, and the backend silently accepts it (for now).
+- **Microservices evolve independently:** Service A updates its contract, but Service B keeps calling the old version. Everything works until it doesn't.
+- **Tests pass, but production breaks:** E2E tests mock the API instead of hitting the real backend, masking contract violations until deployment.
+
+The result? Teams spend hours debugging "why is this suddenly broken?" instead of shipping features.
+
+## The Solution: Mokapi as a Contract Guardian
+
+Mokapi can sit between any client and backend to validate every request and response against your OpenAPI specification.
+With a simple JavaScript forwarding script, Mokapi becomes a transparent validation layer that:
+
+- Blocks invalid requests before they reach your backend
+- Validates backend responses before they reach the client
+- Provides clear, actionable error messages when violations occur
+- Works with browsers, test frameworks, mobile apps, and service-to-service traffic
+
+
+
+## How It Works: Request Forwarding with Validation
+
+The core concept is simple: Mokapi intercepts HTTP traffic, validates it against your OpenAPI spec,
+forwards valid requests to the backend, validates the response, and only then returns it to the client.
+
+Here's the complete forwarding and validation script:
```typescript
import { on } from 'mokapi';
import { fetch } from 'mokapi/http';
/**
- * This script demonstrates how to forward incoming HTTP requests
- * to a real backend while letting Mokapi validate responses according
- * to your OpenAPI spec.
- *
- * The script listens to all HTTP requests and forwards them based
- * on the `request.api` field. Responses from the backend are
- * validated when possible, and any errors are reported back to
- * the client.
+ * Forward incoming requests to backend services while validating
+ * both requests and responses against OpenAPI specifications.
*/
export default async function () {
-
- /**
- * Register a global HTTP event handler.
- * This function is called for every incoming request.
- */
+
on('http', async (request, response) => {
- // Determine the backend URL to forward this request to
+ // Map request to backend URL based on OpenAPI spec name
const url = getForwardUrl(request)
// If no URL could be determined, return an error immediately
@@ -76,7 +90,7 @@ export default async function () {
timeout: '30s'
});
- // Copy status code and headers from the backend response
+ // Copy status code and headers
response.statusCode = res.statusCode;
response.headers = res.headers
@@ -121,146 +135,108 @@ export default async function () {
}
```
-For each interaction, Mokapi performs four important steps:
-
-### 1. Validates incoming requests
-
-Mokapi checks every incoming request against your OpenAPI specification:
-
-- HTTP method
-- URL & parameters
-- headers
-- request body
-
-If the client sends anything invalid, Mokapi blocks it and returns a clear
-validation error.
-
-### 2. Forwards valid requests to your backend
+### The Four-Step Validation Flow
-If the request is valid, Mokapi forwards it unchanged to the backend using JavaScript.
+#### Validate Incoming Request
-- No changes are required in your backend.
-- No additional infrastructure is necessary.
+Mokapi checks the HTTP method, URL parameters, headers, and request body against your OpenAPI spec.
+Invalid requests are blocked with clear error messages.
-### 3. Validates backend responses
+#### Forward Valid Requests
-Once the backend responds, Mokapi validates the response against the OpenAPI specification:
+Only requests that pass validation are forwarded to the backend. No changes to your backend code
+or infrastructure are required.
-- status codes
-- headers
-- response body
+#### Validate Backend Response
-If something doesn't match the contract, Mokapi blocks it and sends a validation error back to the client.
+Mokapi validates the backend's response, status codes, headers, and response body against the OpenAPI specification.
-### 4. Return the validated response to the client
+#### Return Validated Response
-Only responses that pass validation reach the client, guaranteeing contract fidelity end-to-end.
+Only responses that match the contract reach the client, guaranteeing end-to-end contract fidelity across every interaction.
-## Where You Can Use Mokapi for Request Forwarding and Validation
+## Where to Use Mokapi for Contract Validation
-Mokapi’s forwarding and validation capabilities make it useful far beyond local development or Playwright scripting.
+Mokapi's forwarding and validation capabilities work in multiple scenarios across your architecture:
-### Between Frontend and Backend
+### Frontend ↔ Backend
-Placing Mokapi between your frontend and backend ensures:
-- automatic request and response validation
-- immediate detection of breaking changes
-- backend and API specification evolve together
-- fewer “why is the frontend broken?” debugging loops
+Place Mokapi between your frontend and backend to catch contract violations during development:
+- Automatic request and response validation
+- Immediate detection of breaking changes
+- Backend and OpenAPI spec evolve together
+- Fewer "why is the frontend broken?" debugging loops
-Frontend developers can experiment with confidence, knowing the backend
-cannot silently diverge from the published contract.
+### Service ↔ Service
-### Between Backend Services (Service-to-Service)
+In microservice architectures, API drift between services causes instability. Mokapi provides:
+- Strict contract enforcement between services
+- Early detection of incompatible changes
+- Stable integrations as teams evolve independently
+- Clear validation errors during development and CI
-In microservice architectures, API drift between services is a frequent cause of instability.
-Routing service-to-service traffic through Mokapi gives you:
-- strict contract enforcement between services
-- early detection of incompatible changes
-- stable integrations even as teams evolve independently
-- clear validation errors during development and CI
+### Playwright Tests ↔ Backend
-Mokapi becomes a lightweight, spec-driven contract guardian across your backend ecosystem.
+One of the most powerful setups: Playwright → Mokapi → Backend
+- CI fails immediately when backend breaks the contract
+- Tests interact with real backend, not mocks
+- Validation errors are clear and actionable
+- Tests stay simpler, no manual validation needed
-### In Automated Testing (e.g., Playwright)
+### Kubernetes Test Environments
-This is one of the most powerful setups.
+Deploy Mokapi as a sidecar or standalone validation layer in preview environments:
+- Consistent contract validation for cluster traffic
+- Early detection before staging deployment
+- No modifications to backend services
+- Integrates with Helm charts and GitOps workflows
- Playwright → Mokapi → Backend
+## Why Teams Choose This Approach
-Benefits:
-- CI fails immediately when the backend breaks the API contract
-- tests interact with the real backend, not mocks
-- validation errors are clear and actionable
-- tests remain simpler — no need to validate everything in Playwright
-
-Your tests are guaranteed to hit a backend that actually matches the API contract.
-
-### In Kubernetes Test Environments
-
-Mokapi can also be used in temporary or preview environments to ensure contract validation across the entire cluster.
-
-In Kubernetes, Mokapi can be deployed as:
-- a sidecar container
-- a standalone validation layer in front of backend services
-- a temporary component inside preview environments
-
-This brings:
-- consistent contract validation for all cluster traffic
-- early detection of breaking API changes before staging
-- contract enforcement without modifying backend services
-- transparent operation — apps talk to Mokapi, Mokapi talks to the backend
-
-You can integrate Mokapi into Helm charts, GitOps workflows, or test namespaces.
-
-## Why Teams Benefit from Using Mokapi Between Client and Backend
-
-### Automatic Contract Enforcement
-
-Every interaction is validated against your OpenAPI specification. Your backend can no longer quietly drift from the contract.
+``` box=feature title="Automatic Contract Enforcement"
+Every interaction is validated against your OpenAPI spec. Your backend can no longer silently drift from the contract.
+```
-### Immediate Detection of Breaking Changes
+``` box=feature title="Immediate Detection of Breaking Change"
+Issues are caught early, renamed fields, wrong formats, unexpected status codes, mismatched data types before they reach production.
+```
-Issues are caught early, not just in staging or production, such as:
- - renamed or missing fields
- - wrong or inconsistent formats
- - unexpected status codes
- - mismatched data types
+``` box=feature title="More Reliable Frontend Development"
+Frontend teams get consistent, validated API responses with fewer sudden breaking changes and a smoother development workflow.
+```
-### More Reliable Frontend Development
+``` box=feature title="Better Cross-Team Collaboration"
+Backend developers instantly see contract violations. Frontend engineers get stable APIs. QA gets reliable test environments. Platform teams reduce deployment risk.
+```
-Frontend teams get:
-- consistent, validated API responses
-- fewer sudden breaking changes
-- a smoother development workflow
+``` box=feature title="Smooth Mock-to-Real Transition"
+Start with mocked endpoints in early development. Later, simply forward requests to the real backend while keeping validation in place.
+```
-This reduces context-switching and debugging time.
+``` box=feature title="Actionable Error Messages"
+When validation fails, Mokapi provides clear, detailed error messages showing exactly what doesn't match the spec and why.
+```
-### Better Collaboration Between Teams
+> "Mokapi becomes your always-on API contract guardian, lightweight, transparent, and spec-driven."
-With Mokapi validating both sides:
-- backend developers instantly see when they violate the contract
-- frontend engineers get stable, predictable APIs
-- QA gets reliable test environments
-- platform engineers reduce risk during deployments
+## Getting Started
-Mokapi becomes a shared API contract watchdog across the organization.
+Implementing Mokapi as a validation layer is straightforward:
-### Smooth Transition from Mocks to Real Systems
+1. **Define your OpenAPI specification** for the API you want to validate
+2. **Create a forwarding script** using the example above, mapping `request.api` to your backend URLs
+3. **Run Mokapi** between your client and backend (locally, in Docker, or in Kubernetes)
+4. **Point your client** at Mokapi instead of directly at the backend
+5. **Watch validation errors surface** in real-time as you develop, test, and deploy
-Teams often start with mocked endpoints in early development. Later, they can simply begin forwarding requests to the
-real backend—while keeping validation in place.
+No changes to your backend code. No infrastructure overhaul. Just a transparent validation layer
+that enforces your API contract at runtime.
-## Conclusion
+## Stop API Drift. Start Enforcing Contracts.
-Using Mokapi between frontend and backend, between backend services, or inside Kubernetes environments provides:
-- strong contract enforcement
-- automatic validation for every interaction
-- early detection of breaking changes
-- stable multi-team integration
-- more reliable CI pipelines
-- a smooth path from mocking to real backend validation
+With Mokapi as a validation layer, you get automatic contract enforcement, early detection of breaking
+changes, and stable multi-team integration, all without touching your backend code.
-Mokapi ensures your API stays aligned with its specification, no matter how quickly your system evolves.
+{{ cta-grid key="links" }}
-> *Mokapi becomes your always-on API contract guardian — lightweight, transparent, and spec-driven.*
\ No newline at end of file
+
+The dashboard shows:
+- **Message Content:** Full JSON payload with schema validation status
+- **Partition & Offset:** Where the message was stored in the topic
+- **Validation Errors:** Any schema mismatches or missing required fields
+- **Timestamp:** When the message was received by Mokapi
-## Create a Kafka Consumer
+## Create a Kafka Consumer
-Now we can use a .NET Consumer to consume our first sent message.
+Now create a .NET consumer to read messages from the mocked Kafka topic:
```csharp
public class Consumer
@@ -168,4 +235,21 @@ public class Consumer
}
}
}
-```
\ No newline at end of file
+```
+
+### Consumer Code Breakdown
+- **Connection:** Connects to the Mokapi broker at `localhost:9092`
+- **Consumer Group:** Joins consumer group `"foo"`
+- **Offset Reset:** Starts reading from the earliest available
+- **Subscribe:** Subscribes to the `users` topic
+- **Consume Loop:** Continuously polls for new messages and prints them to the console
+
+``` box=result title="Expected Console Output"
+Consumed message '{"id":"dd5742d1-82ad-4d42-8960-cb21bd02f3e7","name":"Alice","email":"alice@foo.bar"}' offset: 0 partition: 1
+```
+
+## Next Steps
+
+Now that you have a working Kafka mock with producer and consumer, explore these advanced topics:
+
+{{ card-grid key="cards" }}
\ No newline at end of file
diff --git a/docs/resources/tutorials/simple-kafka-example.png b/docs/resources/tutorials/simple-kafka-example.png
index fbc8fed8f..1d993c68c 100644
Binary files a/docs/resources/tutorials/simple-kafka-example.png and b/docs/resources/tutorials/simple-kafka-example.png differ
diff --git a/engine/mokapi_on_test.go b/engine/mokapi_on_test.go
index 39b6b724b..ce4394f80 100644
--- a/engine/mokapi_on_test.go
+++ b/engine/mokapi_on_test.go
@@ -238,6 +238,30 @@ export default () => {
test: func(t *testing.T, actions []*common.Action, hook *test.Hook, err error) {
require.NoError(t, err)
+ var res *common.HttpEventResponse
+ err = json.Unmarshal([]byte(actions[0].Parameters[1].(string)), &res)
+ require.Equal(t, map[string]any{"foo": "yuh"}, mokapi.Export(res.Data))
+ },
+ },
+ {
+ name: "using Object.assign",
+ script: `import { on } from 'mokapi'
+export default () => {
+ on('http', (req, res) => {
+ res.data = Object.assign(res.data, {foo: 'yuh'})
+ })
+}
+`,
+ run: func(evt common.EventEmitter) []*common.Action {
+ res := &common.HttpEventResponse{Data: map[string]any{"foo": "bar"}}
+ actions := evt.Emit("http", &common.HttpEventRequest{}, res)
+ require.Nil(t, actions[0].Error)
+ require.Equal(t, map[string]any{"foo": "yuh"}, mokapi.Export(res.Data))
+ return actions
+ },
+ test: func(t *testing.T, actions []*common.Action, hook *test.Hook, err error) {
+ require.NoError(t, err)
+
var res *common.HttpEventResponse
err = json.Unmarshal([]byte(actions[0].Parameters[1].(string)), &res)
require.Equal(t, map[string]any{"foo": "yuh"}, mokapi.Export(res.Data))
diff --git a/examples/kafka/get-started/Dockerfile b/examples/kafka/get-started/Dockerfile
new file mode 100644
index 000000000..5fcbb8a67
--- /dev/null
+++ b/examples/kafka/get-started/Dockerfile
@@ -0,0 +1,5 @@
+FROM mokapi/mokapi:latest
+
+COPY ./kafka.yaml /demo/
+
+CMD ["--Providers.File.Directory=/demo"]
diff --git a/examples/kafka/get-started/Kafka.GetStarted/Consumer.cs b/examples/kafka/get-started/Kafka.GetStarted/Consumer.cs
new file mode 100644
index 000000000..00db6db2f
--- /dev/null
+++ b/examples/kafka/get-started/Kafka.GetStarted/Consumer.cs
@@ -0,0 +1,27 @@
+using System;
+using System.Threading;
+using Confluent.Kafka;
+
+public class Consumer
+{
+ public static void Run()
+ {
+ var config = new ConsumerConfig
+ {
+ BootstrapServers = "localhost:9092",
+ GroupId = "foo",
+ AutoOffsetReset = AutoOffsetReset.Earliest
+ };
+
+ using var consumer = new ConsumerBuilder