DEV Community: GeekyAnts

How Playwright Agents Are Changing the Way We Write and Maintain Tests

GeekyAnts Inc — Fri, 10 Jul 2026 08:10:24 +0000

Adapted from the original post on the GeekyAnts blog.

Ask any automation engineer what their week looks like and you'll hear some version of the same story: read the requirements, write the test cases, script the automation, watch a locator break, chase down why, fix it, run it again. That loop hasn't really gone anywhere — it just moved frameworks, from Selenium to Cypress to Playwright.

So here's a question worth sitting with: what if the framework didn't just run your tests, but actually helped plan them, write them, and repair them when they broke? That's the pitch behind Playwright's Test Agents.

Shipped in Playwright 1.56, these agents bring AI into three specific stages of the testing lifecycle — planning, writing, and healing — by looping against your actual running application rather than guessing from a prompt alone.

This piece walks through what the agents do, how a project gets wired up to use them, what a seed test is for, what comes out the other end, and where this genuinely differs from just asking ChatGPT or Cursor to write you a test script.

Why Playwright Alone Wasn't Enough

Playwright earned its popularity by killing off a lot of the pain that made older frameworks miserable — flaky waits, brittle timing, locators that broke for no obvious reason. Auto-waiting, role-based selectors, and built-in tracing meant engineers spent less time fighting the tool and more time actually testing.

But none of that touched the manual work upstream and downstream of running the tests: translating a requirement doc into concrete scenarios, turning those scenarios into actual code, rewriting tests every time the UI shifts, and chasing broken selectors after every release. Agents are Playwright's attempt to close that gap.

What the Three Agents Actually Do

Playwright Test Agents are AI workflows that live inside a project and split the job into three roles.

The Planner takes a plain-language description of what needs testing, then uses a "seed test" as its entry point into the app to explore flows and edge cases. It comes back with a structured written test plan — not code, but the kind of scenario breakdown a QA engineer would write by hand.

The Generator takes that plan and turns it into runnable Playwright code. Crucially, it does this while poking at the live app — checking that selectors actually resolve, that assertions match real UI state — rather than hallucinating locators from memory. Told to, it'll follow a Page Object Model layout too.

The Healer steps in when a test fails. It re-runs the failing scenario, looks at the current DOM, works out what changed, and tries to patch the selector, wait, or interaction logic itself, instead of leaving that job to whoever's on call.

Chain the three together and the loop becomes Planner, then Generator, then Healer — turning a sentence of intent into a working, self-repairing test suite.

Setting Up a Project

Getting started involves scaffolding a standard Node and Playwright project first, exactly as any engineer already familiar with Playwright would expect. From there, Playwright's own agent tooling can be initialized, which adds a new folder of agent definitions into the project alongside the usual test folders.

That new folder holds three files, one for each agent: the planner, the generator, and the healer, each written as a Markdown definition. Whatever AI assistant is driving the workflow, whether that's Claude Code, VS Code's Copilot, or another agentic coding tool, reads these definitions to understand how to behave in each role.

Alongside the agent definitions, a typical project ends up with a folder for the Markdown plans the Planner produces, a folder for the actual generated Playwright test files, and a single seed test that acts as the Planner's starting point into the application. This layout is the convention Playwright's own tooling expects, so sticking to it keeps things predictable.

The seed test matters more than it sounds like it should. It's the Planner's foothold: where to navigate first, what login step to run, what "home base" looks like for the application before any exploration begins. Alongside it, a small file of sample data (a couple of test user credentials, say — one valid, one intentionally invalid) gives the Planner enough grounding to write scenarios that are actually relevant to the app rather than generic boilerplate.

The Planner Agent in Practice

Think of the Planner less like a code generator and more like a QA analyst that happens to run on AI. Instead of jumping straight to code, it produces a Markdown test plan: scenarios, steps, expected outcomes, and the data each one needs.

A prompt as simple as asking for a test plan covering login with both valid and invalid credentials, using the seed test as context, is enough to get it moving. The Planner explores the app through that seed test and writes out a plan as a readable document, not a script, meant to be read and approved before any code gets written. This is the step where a bad assumption gets caught early, before it turns into a bad test.

The Generator Agent: Plan to Code

Once a plan looks right, the same assistant can be switched into Generator mode and asked to turn that Markdown plan into actual TypeScript tests, following a Page Object Model structure if that's the preference.

The Generator reads the plan, checks selectors and assertions against the live app as it writes, and produces test files — typically one for a straightforward happy path, one covering an edge case, and others built around shared helper functions. Each generated file maps back to a scenario from the plan. Because it's validating against the running app rather than guessing, the output tends to be noticeably more stable than what comes out of a plain prompt-to-code tool with no live context.

The Healer Agent: Fixing What Breaks

Tests fail. A button gets relabeled, a locator moves, and something that passed yesterday doesn't today. Normally that means opening the inspector, finding the new selector, and patching it by hand.

The Healer automates that chase. Pointed at a specific failing test, it re-runs it in debug mode, inspects the current DOM for an equivalent element or flow, proposes a fix such as a new selector or an adjusted wait, and re-runs until it either passes or the agent concludes the failure actually reflects a real product change rather than a stale test. That second outcome matters: the goal isn't to force a green checkmark at any cost, it's to cut down the routine busywork of chasing UI churn.

Under the Hood: What's Actually Happening

From the outside, all of this looks deceptively simple: type a sentence, get back a test plan or a fix. Underneath, the agents run a loop that reads project files, executes real test runs, drives the browser, and inspects the live DOM at every stage. The Planner explores through the seed test, the Generator checks selectors as it writes, the Healer replays failures to diagnose them. That complexity stays hidden — a prompt goes in, a plan, script, or fix comes out, and the orchestration in between isn't something anyone has to manage by hand.

Keeping the Output Organized with Page Object Model

If the generated code needs to stay maintainable long-term, and it should, it's worth being explicit about that in the prompt: asking for a Page Object Model structure with locators kept in separate page files. That nudges the Generator toward splitting locator definitions and reusable actions into their own files, separate from the test logic itself, which saves a lot of refactoring down the line.

The Full Loop, End to End

Run all three agents together and the shape of the workflow is: a seed test plus a prompt goes to the Planner, which writes a Markdown plan; that plan goes to the Generator, which writes the tests; those tests run, and any failures go to the Healer, which fixes what it can. What comes out the other side is a test suite that largely maintains itself. It's the same lifecycle a human QA team already runs, just with AI doing the first draft at every stage.

Where This Differs From Generic AI Coding Tools

It's tempting to lump this in with Cursor, ChatGPT, or any other "AI writes my code" tool, but the comparison doesn't hold up well. Generic AI code generation can write code from a prompt, but it doesn't run the tests it writes, doesn't fix failures on its own, and doesn't check the live DOM while generating. Playwright Agents do all three, and they do it wired directly into Playwright's own tooling through MCP (Model Context Protocol), staying in the loop with the running application throughout rather than generating code from a prompt in isolation.

A Few Things That Make This Work Better

Giving the agents real context matters more than clever prompting — a well-built seed test and structured seed data make a bigger difference than a cleverly worded instruction. Prompts should be specific about architecture preferences, data sources, and expected outputs rather than left open-ended. Generated tests are still worth a human read-through; good scaffolding isn't the same as a finished, reviewed test. And in CI, healed or freshly generated tests are best treated as drafts until someone's actually looked at them.

Wrapping Up

Between the Planner, Generator, and Healer, Playwright's agents take a real bite out of the manual overhead in test automation, turning a plain-language description into scenarios, code, and self-repair without cutting humans out of the review loop.

Anyone with basic Playwright experience already has most of what they need to try this. It's the same lifecycle, with AI doing more of the first draft. Worth trying on a small project first: set up the agents, write a decent seed test, and see how far a simple prompt actually gets.

Adapted from the original article on the GeekyAnts blog.

Building a Production-Ready Image Cropper in React Native

GeekyAnts Inc — Thu, 09 Jul 2026 07:13:15 +0000

Originally published on the GeekyAnts Blog.

Build a production-ready, gesture-driven image cropper from scratch — supporting circular profile crops, rectangular cover crops, draggable windows, resizable corners, and pixel-perfect coordinate mapping back to the original image.

Introduction

In modern mobile applications, image handling is a core experience. Whether uploading a profile picture or setting a cover image, users expect precision, control, and real-time feedback.

While third-party libraries exist, they often introduce heavy dependencies or limit customization. In this article, we'll build a fully custom, gesture-driven image cropper using React Native and expo-image-manipulator — supporting both circular profile crops and rectangular cover crops.

Why expo-image-manipulator?

expo-image-manipulator provides a native bridge for performing image transformations efficiently. All operations — crop, resize, rotate, flip — execute on the native thread, which means they don't block the JS runtime and scale well even on lower-end Android devices.

Compared to pure JS image-processing approaches, the native execution path avoids decoding the full bitmap into a JS array buffer, which can easily exhaust memory on high-resolution photos. The library also handles format conversion (JPEG, PNG, WEBP) and compression in a single pass, so you aren't writing a cropped image to disk and then re-encoding it for upload — the final manipulateAsync call produces the upload-ready file directly.

The package ships two API styles. The legacy imperative API (manipulateAsync) applies a list of transforms in a single async call — ideal for a one-shot crop like ours. The newer context-based API (useImageManipulator / ImageManipulator.manipulate) enables chainable, background-threaded transforms and shines when you need to compose many operations interactively without writing intermediate files to disk. We'll use the imperative API throughout this post.

Installation & Setup

Install via the Expo CLI so the correct native version is automatically matched to your SDK:

npx expo install expo-image-manipulator

For a bare React Native project (without Expo Go), also run the iOS pod install:

npx pod-install

No additional permissions are required. The manipulator operates entirely on local file URIs produced by your image picker — it never touches the camera roll or network directly.

expo-image-manipulator API Overview

We'll use the imperative API — it's perfectly suited to a one-shot crop operation.

Core Function

ImageManipulator.manipulateAsync(
  uri,        // local file URI or base64 data URI
  actions,    // array of transformation objects
  saveOptions // format, compress, base64
)

It returns a Promise which resolves to:

Field	Type	Description
url	string	Local URI to the new file (cached)
width	number	Width of the output image in pixels
height	number	Height of the output image in pixels
base64	string?	Base64 payload if base64: true was passed

Available Actions

Action key	Parameters	What it does
crop	originX, originY, width, height	Crops a rectangular region (in original image pixels)
resize	width, height	Scales the image; omit one dimension to keep ratio
rotate	degrees	Clockwise rotation
flip	"horizontal" \| "vertical"	Mirror along an axis
extent	originX, originY, width, height, backgroundColor	Canvas resize with optional padding fill

Save Options

Option	Type	Default	Description
format	SaveFormat	JPEG	JPEG, PNG, or WEBP
compress	0.0 – 1.0	1.0	1 = highest quality, 0 = maximum compression
base64	boolean	false	Include raw base64 in the result

Component Architecture

The component lives inside an action sheet and owns three pieces of state that together describe the current crop selection:

containerSize — measured width and height of the image container, captured via onLayout
cropPosition — the top-left corner of the crop window in container-space coordinates ({ x, y })
windowDimensions — the current width and height of the crop window in container space

All crop math operates in container space first, then gets converted to original image pixel space at the moment the user taps Crop. This separation keeps gesture handling fast and stateless — no expensive native calls happen during a drag.

Props

interface ImageCropProps {
  showCropper:        boolean;
  handleClose:        () => void;
  selectedUploadType: 'profile' | 'cover';
  uploadFunction:     (data: ImageManipulator.ImageResult) => void;
  tempImage:          string;  // local URI from image picker
}

On mount, two effects run in sequence: the first sets windowDimensions based on the upload type (square for profile, wide rectangle for cover), and the second centers the crop window inside the container once both sizes are known.

// Profile: square up to 200 px. Cover: full width × 150 px.
useEffect(() => {
  if (containerSize.width > 0) {
    if (selectedUploadType === 'profile') {
      const size = Math.min(containerSize.width, 200);
      setWindowDimensions({ width: size, height: size });
    } else {
      setWindowDimensions({ width: containerSize.width, height: 150 });
    }
  }
}, [containerSize, selectedUploadType]);

// Center the window once both sizes are known
useEffect(() => {
  if (containerSize.width > 0 && windowDimensions.width > 0) {
    setCropPosition({
      x: (containerSize.width  - windowDimensions.width)  / 2,
      y: (containerSize.height - windowDimensions.height) / 2,
    });
  }
}, [containerSize, windowDimensions]);

Building The Drag & Resize System

Dragging the crop window

The crop window is a positioned View sitting absolutely on top of the image. A PanResponder attached to its inner area tracks the gesture delta (dx, dy) and updates cropPosition, clamping it so the window never exits the container boundary.

One subtle requirement: the pan responder must not activate when the touch originates inside one of the 20 px corner zones — otherwise the drag and resize responders fire simultaneously and produce jittery, conflicting movement. We check touch coordinates in onStartShouldSetPanResponder and return false for corner touches.

const panResponder = useMemo(() =>
  PanResponder.create({
    onStartShouldSetPanResponder: (evt) => {
      const { locationX: x, locationY: y } = evt.nativeEvent;
      const cs = 20;
      const inCorner =
        (x <= cs || x >= windowDimensions.width  - cs) &&
        (y <= cs || y >= windowDimensions.height - cs);
      return !inCorner;
    },
    onMoveShouldSetPanResponder: (evt) => {
      // Mirrors onStartShouldSetPanResponder — keeps both predicates in sync
      const { locationX: x, locationY: y } = evt.nativeEvent;
      const cs = 20;
      return !(
        (x <= cs || x >= windowDimensions.width  - cs) &&
        (y <= cs || y >= windowDimensions.height - cs)
      );
    },
    onPanResponderMove: (_, { dx, dy }) => {
      setCropPosition({
        x: Math.max(0, Math.min(
          cropPosition.x + dx,
          containerSize.width - windowDimensions.width
        )),
        y: Math.max(0, Math.min(
          cropPosition.y + dy,
          containerSize.height - windowDimensions.height
        )),
      });
    },
  }),
  [containerSize, cropPosition, windowDimensions]
);

Why useMemo matters here

The pan responder captures cropPosition and windowDimensions in its closure at creation time. Without useMemo, a new responder is created on every render, but the gesture system holds a reference to the original — meaning your move handler reads stale state and the crop window drifts noticeably during a fast drag. Wrapping in useMemo with the correct dependency array ensures the responder is always reading current values.

Resizing with corner handles

Each of the four corner handles has its own PanResponder, created by a factory function. The geometry differs per corner: dragging bottom-right simply extends width and height, while dragging top-left must simultaneously shrink the window and shift its origin so the opposite corner stays anchored in place.

const createCornerPanResponder = (
  corner: 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight'
) => PanResponder.create({
  onStartShouldSetPanResponder: () => true,
  onPanResponderMove: (_, { dx, dy }) => {
    let newW = windowDimensions.width;
    let newH = windowDimensions.height;
    let newX = cropPosition.x;
    let newY = cropPosition.y;
    switch (corner) {
      case 'bottomRight':
        newW = Math.max(minDimensions.width,  windowDimensions.width  + dx);
        newH = isProfile ? newW : Math.max(minDimensions.height, windowDimensions.height + dy);
        break;
      case 'topLeft':
        newW = Math.max(minDimensions.width,  windowDimensions.width  - dx);
        newH = isProfile ? newW : Math.max(minDimensions.height, windowDimensions.height - dy);
        newX = cropPosition.x - (newW - windowDimensions.width);
        newY = cropPosition.y - (newH - windowDimensions.height);
        break;
      case 'topRight':
        newW = Math.max(minDimensions.width,  windowDimensions.width  + dx);
        newH = isProfile ? newW : Math.max(minDimensions.height, windowDimensions.height - dy);
        newY = cropPosition.y + (windowDimensions.height - newH);
        break;
      case 'bottomLeft':
        newW = Math.max(minDimensions.width,  windowDimensions.width  - dx);
        newH = isProfile ? newW : Math.max(minDimensions.height, windowDimensions.height + dy);
        newX = cropPosition.x - (newW - windowDimensions.width);
        break;
    }
    // Commit only if the new geometry fits entirely within the container
    if (
      newX >= 0 && newY >= 0 &&
      newX + newW <= containerSize.width &&
      newY + newH <= containerSize.height
    ) {
      setWindowDimensions({ width: newW, height: newH });
      setCropPosition({ x: newX, y: newY });
    }
  },
});

For profile mode, height is always forced equal to width (newH = newW) regardless of which corner is dragged, preserving a perfect 1:1 aspect ratio at every resize step. Cover mode allows independent width and height resizing, subject to configurable minimum dimensions.

Coordinate Mapping: Display → Original Pixels

This is the most critical — and most commonly misunderstood — part of building a custom cropper. Your crop window lives in container space (screen pixels inside the View), but manipulateAsync expects coordinates in original image pixel space. The two are not the same.

When an image is rendered with contentFit="cover", React Native scales it so the shorter dimension fills the container exactly — and the longer dimension overflows and is clipped. This means part of the image is hidden off-screen, and any crop coordinate you compute from container space will be offset by exactly that hidden amount unless you correct for it.

The conversion has five steps:

Step 1 — Get the original image dimensions. Call manipulateAsync with an empty actions array. This is a lightweight metadata read with no transformation cost.

const imageInfo = await ImageManipulator.manipulateAsync(
  tempImage, [], { compress: 1 }
);

Step 2 — Determine the displayed dimensions. Compare aspect ratios to find which axis is the constraining one.

const imgAR       = imageInfo.width / imageInfo.height;
const containerAR = containerSize.width / containerSize.height;
let displayedW, displayedH;
if (imgAR > containerAR) {
  // Image is wider than container — height fills, width overflows left/right
  displayedH = containerSize.height;
  displayedW = containerSize.height * imgAR;
} else {
  // Image is taller than container — width fills, height overflows top/bottom
  displayedW = containerSize.width;
  displayedH = containerSize.width / imgAR;
}

Step 3 — Compute the overflow offset. The image is centered inside the container, so the hidden portion is split equally on both sides.

const offsetX = (displayedW - containerSize.width)  / 2;  // 0 when image is taller
const offsetY = (displayedH - containerSize.height) / 2;  // 0 when image is wider

Step 4 — Compute scale factors between the original image and the displayed image.

const scaleX = imageInfo.width  / displayedW;
const scaleY = imageInfo.height / displayedH;

Step 5 — Convert UI coordinates to image coordinates.

const actualCropX = Math.round((cropPosition.x + offsetX) * scaleX);
const actualCropY = Math.round((cropPosition.y + offsetY) * scaleY);

Executing The Crop — Profile & Cover

Profile Photo (square, resized to 200 x 200)

For a profile photo, we want a square crop. We clamp the crop size so it never requests pixels beyond the image boundary, then chain a resize to normalise all uploads to 200 × 200 regardless of how large the user's original photo was.

const actualCropSize = Math.round(windowDimensions.width * scaleX);
const finalSize = Math.min(
  actualCropSize,
  imageInfo.width  - actualCropX,
  imageInfo.height - actualCropY,
);
const croppedImage = await ImageManipulator.manipulateAsync(
  tempImage,
  [
    { crop: {
        originX: actualCropX, originY: actualCropY,
        width:   finalSize,   height:  finalSize,
    }},
    { resize: { width: 200, height: 200 }},
  ],
  { compress: 1, format: ImageManipulator.SaveFormat.JPEG }
);
uploadFunction(croppedImage);

Cover photo (rectangular)

The cover crop uses independent width and height scale factors and clamps each dimension separately so neither ever exceeds the remaining pixels after the crop origin.

const actualCropW = Math.min(
  Math.round(windowDimensions.width  * scaleX),
  imageInfo.width  - actualCropX,
);
const actualCropH = Math.min(
  Math.round(windowDimensions.height * scaleY),
  imageInfo.height - actualCropY,
);


const croppedImage = await ImageManipulator.manipulateAsync(
  tempImage,
  [{ crop: {
      originX: actualCropX, originY: actualCropY,
      width:   actualCropW,  height:  actualCropH,
  }}],
  { compress: 1, format: ImageManipulator.SaveFormat.JPEG }
);
uploadFunction(croppedImage);

The Darkened Overlay Cutout

Rather than a single semi-transparent layer with a punched-out hole (which requires SVG clip-paths or canvas rendering), we use four darkened Views — one for each side of the crop window. Their positions and sizes are derived directly from cropPosition and windowDimensions, so they update in real time as the user drags or resizes without any additional state.

{/* Top — spans full width, height = distance from top to crop window */}
<View style={{ position: 'absolute', top: 0, left: 0, right: 0,
  height: cropPosition.y, backgroundColor: 'rgba(0,0,0,0.5)' }} />
{/* Bottom — starts where the crop window ends */}
<View style={{ position: 'absolute', bottom: 0, left: 0, right: 0,
  height: containerSize.height - (cropPosition.y + windowDimensions.height),
  backgroundColor: 'rgba(0,0,0,0.5)' }} />
{/* Left — only spans the crop window's row to avoid double-darkening corners */}
<View style={{ position: 'absolute', top: cropPosition.y, left: 0,
  width: cropPosition.x, height: windowDimensions.height,
  backgroundColor: 'rgba(0,0,0,0.5)' }} />
{/* Right — mirrors left */}
<View style={{ position: 'absolute', top: cropPosition.y, right: 0,
  width: containerSize.width - (cropPosition.x + windowDimensions.width),
  height: windowDimensions.height,
  backgroundColor: 'rgba(0,0,0,0.5)' }} />

Inside the crop window, the border style switches between a full-radius dashed circle (borderRadius: 999, borderStyle: 'dashed') for profile mode and a plain solid rectangle for cover mode. A rule-of-thirds grid is drawn with four thin Views at 33% and 66% positions, giving users a professional alignment guide without any additional library.

Usage

import { ImageCrop } from './ImageCrop';


const MyScreen = () => {
  const [showCropper, setShowCropper] = useState(false);
  const [pickedImage,  setPickedImage]  = useState<string | null>(null);
  const handleUpload = (result: ImageManipulator.ImageResult) => {
    uploadToServer(result.uri);
    setShowCropper(false);
  };
  return (
    <>
      {/* ... rest of your screen ... */}
      {pickedImage &&
        <ImageCrop
          showCropper={showCropper}
          handleClose={() => setShowCropper(false)}
          selectedUploadType="profile"
          tempImage={pickedImage}
          uploadFunction={handleUpload}
        />
      }
    </>
  );
};

UX Enhancements

Grid lines (rule of thirds)
Corner handles for resizing
Loading overlay during processing
Auto-centered crop window
Dynamic resizing based on container

Performance Considerations

Avoid repeated manipulateAsync calls
Use useMemo for gesture handlers
Perform crop only on user confirmation
Use compression wisely (0.8–1)

Advanced Extensions

Pinch-to-zoom support
Rotation & flipping controls
Circular live preview
Cloud upload integration (S3/Firebase)
Combined zoom + crop gestures

Summary & Key Takeaways

Building a custom image cropper in React Native gives you full control over UX, performance, and flexibility.

Key learnings:

expo-image-manipulator handles heavy image processing natively
PanResponder is sufficient for complex gesture interactions
Coordinate mapping is the backbone of accurate cropping
Overlay-based masking provides a clean UI without extra dependencies
Supporting multiple crop modes requires thoughtful architecture

This approach is particularly valuable for applications handling user-generated content, where performance, flexibility, and consistent media output directly impact user experience and scalability.

Special thanks to Deepanshu Goyal for architectural guidance and review.

This article was originally published on the GeekyAnts Blog.

Geeklego: The Open-Source Design System Built to Work With AI

GeekyAnts Inc — Wed, 08 Jul 2026 11:02:49 +0000

Fork it. Define your 3-tier design system. Let Claude Code, Codex, Gemini CLI — or any AI coding tool — generate a consistent, accessible UI that can never break your design rules.

Originally published on the GeekyAnts Blog.

The Problem With Design Systems in the Age of AI

Design systems are supposed to bring consistency. But in practice, they are a document that developers mean to follow, a Notion page that's three months out of date, and a set of tokens that might or might not match what's actually in the code.

Now add AI coding tools to the picture. Claude Code, Codex, Gemini CLI, and Cursor — these tools generate components fast. Impressively fast. But fast without constraints is how you end up with hardcoded hex values, skipped token tiers, and five different ways to truncate text across a codebase that was supposed to be consistent.

The problem is structural: design systems are defined separately from the rules that enforce them. AI tools have no way to know that --color-brand-500 should never appear directly in a component, or that every spacing value must come from a semantic token, or that dark mode only works if you respect the semantic tier. No one told the AI. So it guesses — and it guesses consistently wrong in different ways.

Geeklego is our answer to this problem. And it's open source.

What Is Geeklego?

Geeklego is an open-source, AI-native design system built on Tailwind CSS v4. It ships three things:

A 3-tier design system — a single CSS file (geeklego.css) that defines every visual value across three strict tiers: raw primitives, purpose-driven semantics, and component-specific tokens. It is the authoritative, machine-readable source of truth for the entire project.
A skill layer — six AI skills (for Claude Code, Codex, Gemini CLI, or any agent-capable tool) that generate components, sync with Figma, audit for accessibility and security, and add internationalization — all while enforcing the 3-tier architecture automatically.
81 production-ready components — atoms, molecules, and organisms that are expressions of the design system, each generated by the skill layer and proven to follow the rules.

Geeklego is not a component library you install and override. It's a design system you own and extend — with an AI layer that makes extension fast, consistent, and safe.

The philosophy is simple: define the system first. Let AI build from it, not around it.

The Vision: A Design System That Teaches Itself to AI

Every AI coding tool — Claude Code, Codex, Gemini CLI, Cursor — is only as good as the context it has. Give it no context, and it invents conventions. Give it a good context, and it follows yours.

Geeklego's vision is to make the design system itself that context. Not a README that someone has to remember to reference. Not a Storybook that AI can't read. The actual architecture — the 3-tier token chain, the 5-file component structure, the 45 explicit rules — is encoded in a machine-readable spec (CLAUDE.md) that any AI coding tool can consume before it writes a single line.

AI that is constrained by your design system, not set loose on your codebase.

When any AI tool generates a component in Geeklego, it can't hardcode #6366f1. It can't use h-[40px]. It can't reference a Tier 1 primitive directly from a component. The architecture makes inconsistency structurally impossible — not a guideline someone has to remember, not a lint rule someone can suppress.

The long-term vision: you define the system once. Every AI that ever touches your codebase — today's tools, next year's tools, tools that don't exist yet — generates components that follow it perfectly. Hundreds of components, zero design drift. That's what Geeklego is building toward.

Design-System-First: The 3-Tier Architecture That Changes Everything

In every component library you've used, the design system emerges from component code. You build a Button, extract its colors into variables, build a Card, extract its spacing, and over time something resembling a design system appears.

Geeklego inverts this completely.

Before a single component is written, the design system is defined and published across three distinct tiers. Components are built as expressions of the system, constrained to use only what the system provides — and only in the order the system prescribes.

The 3-Tier Token Chain

This is the central idea in Geeklego. Everything else flows from it.

Tier 1 — Primitives are raw values: --color-brand-500: #6366f1, --spacing-4: 1rem. They are the foundation of the entire system. No component ever references a primitive directly. That's the rule.

Tier 2 — Semantics give purpose to primitives: --color-action-primary: var(--color-brand-500). This is where theming happens. When you switch to dark mode, semantic tokens update. Primitives stay unchanged. The semantic tier is the single mechanism that makes theme switching work correctly across every component in the library simultaneously.

Tier 3 — Component tokens bind individual components to semantics: --button-bg: var(--color-action-primary). A component token must always reference a Tier 2 semantic. Referencing a primitive directly — skipping Tier 2 — is forbidden. This is non-negotiable, encoded in the architecture, and enforced by the Claude Code skill before it writes a single line of component code.

Here's the full chain for a Button's background color:

/* Tier 1 — Primitives*/
/--color-brand-500: #6366f1;

/* Tier 2 — Semantics*/
/--color-action-primary: var(--color-brand-500);

/ Tier 3 — Component tokens*/
/--button-bg: var(--color-action-primary);

And in a component:

<button className="bg-[var(--button-bg)] ...">Submit</button>

Here's why all three tiers are necessary. When you toggle dark mode, you update one Tier 2 semantic:

[data-theme="dark"] {  --color-action-primary: var(--color-brand-400);}

That is the only change. Every component that reads --button-bg picks up the new value through the chain — automatically, correctly, everywhere. No per-component dark mode overrides. No !important patches. No missing cases discovered in production.

If a component token had skipped Tier 2 and referenced a Tier 1 primitive directly, that component would be invisible to theme switches. It would render the same color in light and dark mode, and you'd never know why until a designer filed a bug report.

The 3-tier chain is not a bureaucracy. It's the mechanism that makes the entire system coherent.

No Arbitrary Values. Ever.

The 3-tier chain only works if it's airtight. So Geeklego forbids Tailwind arbitrary values like bg-[#6366f1] or h-[40px]. Every value — every color, every size, every spacing unit — must flow through all three tiers and arrive as a Tier 3 component token.

The only permitted syntax is bg-[var(--button-bg)], wrapping a Tier 3 CSS variable in Tailwind v4's arbitrary value syntax.

This constraint has a profound side effect: AI can only generate valid, chain-compliant code. When Claude Code generates a component, there's nowhere to put a hardcoded value. The language doesn't permit it. Design integrity is enforced by architecture, not code review.

What Ships With Geeklego Today

81 Production-Ready Components

Geeklego currently ships three levels of the component hierarchy:

L1 Atoms (38 components) — the building blocks: Avatar, Badge, Button, Checkbox, Input, Select, Spinner, Switch, Tooltip, and 29 more. Atoms import nothing — they're pure expressions of the design system.

L2 Molecules (27 components) — combinations of atoms: AlertBanner, Breadcrumb, ButtonGroup, Calendar, Card, Combobox, DateInput, DropdownMenu, Fieldset, FormField, InputGroup, Navbar, NumberInput, Pagination, Popover, RadioGroup, SearchBar, StatCard, Stepper, Toast, Tooltip, TreeView, and more.

L3 Organisms (16 components) — full UI sections: Accordion, AreaChart, BarChart, Carousel, Chat, ColorPicker, DataTable, Datepicker, Drawer, Footer, Form, Header, Modal, PieChart, Sidebar, Tabs, and more in active development.

L4 Templates and L5 Pages are in active development. DashboardLayout, AuthLayout, and LandingLayout are coming next.

Every component in the fork ships with:

Full TypeScript types and JSDoc-annotated props
Light and dark mode support out of the box, via the 3-tier token chain
WCAG 2.2 Level AA accessibility (keyboard nav, ARIA, focus management)
Responsive design via Tailwind responsive prefixes
8 Storybook stories per component (used as automated tests via Vitest)
Optional Schema.org markup for SEO
Optional i18n string support

A Visual Token Editor

npm run dev opens a full React app at localhost:5176 for editing the design system without touching code.

A three-panel layout: a left NavRail organizes tokens into three tiers (Foundations with 8 sub-categories like color, spacing, typography, and shadow; Semantic with purpose-driven alias groups; Components listed by level) with drill-down sub-categories, a center pane shows the selected category or component, and a right Inspector panel displays token details with value editing and alias chain visualization. Export is available from the header bar. Changes preview instantly across Storybook via WebSocket. Full undo/redo history. Automatic backup. Token validation. Export as CSS or JSON.

This means designers can edit the design system directly. Not in a Notion doc that may or may not reflect the code. In the actual source of truth, with live preview.

Storybook as Living Tests

Geeklego treats Storybook stories as executable tests. Each .stories.tsx file becomes a Vitest test running headless in Chromium via Playwright. No separate test infrastructure. Stories serve double duty as documentation and automated regression tests.

Every component requires eight stories: default, variant A, variant B, size/scale, disabled state, loading state, dark mode, and an accessibility story tagged for WCAG audit.

The Skill Layer: AI That Knows the Rules

This is the part of Geeklego that has no equivalent in any other design system.

Geeklego ships with six skills — self-contained, machine-readable workflow definitions that any capable AI coding tool can execute. They work today with Claude Code, and are designed to be portable to Codex, Gemini CLI, or any agent-capable environment that can read a prompt file and call tools.

Each skill is not a prompt template. It's a disciplined workflow that reads the design system state first, validates the 3-tier chain, applies the change, then runs a verification pass. The AI doesn't guess. It follows a documented process.

The Six Skills

/component-builder — The flagship skill. Invoke it with any component description and the AI reads geeklego.css, verifies no token block already exists, writes Tier 3 component tokens (each correctly referencing a Tier 2 semantic), generates all five required files, then runs four sequential audits: accessibility, performance, SEO, and security. A component that takes a human two to three hours ships in two to three minutes — and is structurally guaranteed to follow the token chain.

/component-builder build a Tooltip atom/component-builder build a StatCard molecule/component-builder build a DataTable organism with sorting and pagination

/figma-sync — Sync your Tier 1–3 token definitions to Figma variable collections and text styles automatically. The skill diffs the current Figma state against geeklego.css, reports what's out of sync, then creates or updates variables to match. Design and code never drift apart.
/i18n — Add internationalization to any component without committing to a specific i18n library. Library-agnostic, prop-first architecture with RTL support via logical CSS properties. Reads the string inventory to know which system strings already have i18n coverage.
/state-handling — Audit and generate visual state patterns. Every interactive component needs correct loading, disabled, error, and selected states with proper ARIA attributes. This skill reads the state-handling reference, validates what exists, and generates what's missing.
/security-review — Audit components for XSS vulnerabilities, unsafe href handling, missing rel="noopener" on external links, and unsanitized user input. Runs against the full component tree.
/screenshot-workflow — Generate component screenshots automatically for documentation, changelogs, or CI/CD visual regression pipelines.

On-Demand Audit Commands

Beyond the skills, natural-language audit commands run across the entire codebase:

do a refactor check     # Memoization, hooks compliance, performance utility usagedo a reuse audit        # Find inlined markup that should use existing atomsdo an SEO audit         # Schema.org coverage, semantic HTML, heading hierarchy

The Machine-Readable Spec

The skills work because the design system's rules are encoded in a machine-readable spec — CLAUDE.md — that any AI coding tool reads before starting any task. It contains 45 explicit "never do" rules, 49 "always do" rules, naming conventions, the token chain hierarchy, component level definitions, and reference documents for worked examples, semantic HTML, ARIA patterns, and Schema.org mappings.

This is not a README for humans. It's a contract for AI. Every tool that reads it gets the same constraints. Design integrity is preserved not by hoping the AI guesses right, but by telling it exactly what right means — before it generates a single token.

How Geeklego Differs From Other Design Systems

Most design systems are collections of decisions: here are the colors, here are the spacing values, here is a Figma file. Implementation is left to the team. Consistency depends on culture, code review, and people remembering the rules.

Geeklego is a design system that enforces its own rules. Not through linting, not through code review, not through policy — through architecture. The 3-tier chain makes it structurally impossible to introduce a hardcoded value or skip a token tier, because the skill that generates components checks the chain before writing anything. And the machine-readable spec means any AI tool you bring to the project inherits those constraints immediately.

Feature	Typical design system	Geeklego
Token architecture	Ad hoc or flat	Strict 3-tier chain: primitives → semantics → component tokens
Dark mode	Per-component overrides	Automatic — update Tier 2 semantics, all components cascade
AI compatibility	Unstructured — AI must guess conventions	Machine-readable spec — AI reads the rules before generating anything
Component generation	Manual	Skill-driven with full 3-tier validation and audit pipeline
Figma integration	Manual, periodic sync	Automated sync skill, diff-aware
Token editor	External tools or none	Built-in visual editor with live preview
Accessibility	Depends on the team	WCAG 2.2 AA baked into the component-builder skill
i18n	Separate effort	Library-agnostic pattern, built into the skill layer
Multi-brand support	Fork and diverge	Fork and share component logic; only tokens differ

The shift is from "design system as document" to "design system as enforced architecture." One you reference. The other you can't break.

Real-World Use Cases

Rapid prototyping. Edit the design system in the token editor. Use /component-builder to generate components that match. Preview in Storybook. Sync tokens to Figma for designer feedback. When the design is locked, your production components are ready. Two days instead of two weeks.

Design system governance at scale. Define your tokens. Every team generates components via /component-builder — they can't deviate because the architecture prevents it. Run audits on PRs. The design system becomes enforceable by architecture, not by policy. Code reviews drop from 30 minutes to 5 minutes.

Multi-brand products. Fork Geeklego twice. Each fork has its own geeklego.css with its own colors, fonts, and spacing. Both forks share identical component logic. Update the logic once, both brands benefit. Maintain one codebase, support multiple brands.

Accessible component libraries. Accessibility is built into the component-builder skill — not bolted on after. Every generated component includes the right ARIA attributes, keyboard navigation patterns, touch targets, and semantic HTML. WCAG 2.2 AA by default, not by accident.

Getting Started: Fork and Make It Yours

Geeklego is designed to be forked, not installed. Forking gives you the full 3-tier design system, the visual token editor, all 81 components, and every AI skill — everything you need to customize the system and build from it.

# 1. Fork the repo on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/geeklego.git
cd geeklego

# 2. Install dependenciesnpm install

# 3. Start both the token editor and Storybooknpm run dev:all

Two apps open:

localhost:5176 — the token editor: customize your Tier 1–3 tokens visually, no code required
localhost:6006 — Storybook with all 81 components, live-connected to the token editor

Open your AI tool and start building:

# With Claude Code

/help                                # see all available skills
/component-builder build a [ComponentName]  # generate a new component end-to-end

# With Gemini CLI or Codex

# Point your agent at CLAUDE.md as system context,

# then trigger the same skill workflows from the .claude/skills/ directory

The machine-readable spec in CLAUDE.md is read automatically by Claude Code before every task. For Codex, Gemini CLI, or other agent-capable tools, pass CLAUDE.md as your system context — it's plain markdown and works with any tool that accepts instruction files.

Customize your design system:

Open the token editor at localhost:5176. Edit Tier 1 primitives (your brand colors, spacing scale, type sizes), Tier 2 semantics (what each primitive means in context), and watch every component in Storybook update in real time. When you're ready, export as CSS or JSON.

That's it. The design system is yours. The components follow it automatically. The AI skill layer keeps new components consistent with it, forever.

How to Contribute

Geeklego is open source and actively welcoming contributors. The remaining work on the roadmap includes HeroSection (L3), DashboardLayout, AuthLayout, and LandingLayout (L4 Templates).

Every contribution follows the same pattern — 5 files, the 3-tier token chain, 8 Storybook stories. The machine-readable spec and the skill layer make it straightforward to use your AI tool of choice to generate a contribution that meets the bar from the first commit. You don't need to memorize the rules — the spec teaches the AI, and the AI generates compliant code.

GitHub: https://github.com/GeekyAnts/geeklego
Website: https://geeklego.io
Issues & discussions: open a thread on GitHub

Give it a star, open an issue, or fork it — use /component-builder to generate your contribution and it'll follow the rules from the first commit. We'd love to see what you build.

Geeklego is open source under the MIT license. Built with React 19, Tailwind CSS v4, Vite 6, Storybook 10, and Vitest.

Originally published at geekyants.com/blog.

The Keyboard Bounce of Death: Handling Inputs on Complex React Native Screens

GeekyAnts Inc — Fri, 03 Jul 2026 13:01:37 +0000

Modern React Native has evolved significantly—Expo's new architecture is stable, Hermes is the default engine, layout rendering has improved, and libraries like Reanimated and React Native Screens are widely adopted. Yet one issue continues to frustrate even experienced engineers:

The Keyboard Bounce of Death

Your inputs jump, shift, or completely hide behind the keyboard—a frustrating experience that makes your app feel buggy and cheap.

If you are building login screens, onboarding flows, multi-step forms, or bottom-sheet-based UIs… you've likely seen this happen.

This article explains why this problem still occurs in modern React Native setups and provides battle-tested solutions you can confidently use in production.

Version Context

The examples and recommendations are written with current (2024–2025) React Native stacks in mind, commonly seen in production apps today:

React Native: 0.74+
React: 18
Expo SDK: 50+ (New Architecture enabled)
Hermes: Enabled (default)
react-native-keyboard-controller: 1.20.x
react-native-reanimated: 3.x
react-native-screens: 3.x
@shopify/flash-list: 1.x

These versions are provided for context rather than certification.

Exact behavior may vary depending on project configuration, cross-platform (iOS / Android), and library versions. Readers should validate keyboard behavior against their own application stack.

The Real Problem: Keyboard Handling Breaks at the Architecture Level

In modern React Native applications, keyboard issues are no longer caused by misconfigured props or missing offsets. The failure is architectural.

Classic solutions such as KeyboardAvoidingView assume a synchronous, stable layout model. That assumption no longer holds in React Native's current execution environment, where rendering, layout, and native events operate on partially decoupled timelines.

Where the breakdown happens

1. Layout virtualization (React Native Screens ~3.30.x)

Navigation stacks aggressively detach inactive screens to reduce memory and improve performance. This means:

The active screen's layout is often unresolved during transitions
Height measurements are stale at the moment keyboard events fire
Offset calculations are applied against incomplete layout data

Keyboard avoidance logic executes correctly—but against the wrong inputs.

2. Concurrent Rendering Changes Layout Timing (RN 0.74+)

With React 18 integration and the New Architecture, React Native now supports concurrent rendering. Unlike legacy synchronous rendering, concurrent rendering allows work to be interruptible and scheduled across frames.

This changes long-standing assumptions about layout timing:

Layout commits are no longer guaranteed to be synchronous.
Native keyboard events can fire before the React tree has fully committed.
Measurements taken during focus events may reflect intermediate layout states.

In complex screens (navigation stacks, bottom sheets, nested scroll views), this can produce visible misalignment:

Keyboard height is computed.
Offset is applied.
Layout commits afterward.
The UI shifts again.

The result appears as a "bounce," but the underlying issue is timing desynchronization between native keyboard animations and React layout commits.

This is not a bug in React Native — it is a natural consequence of concurrent rendering's scheduling model.

3. Android keyboard behavior is non-deterministic by design

On Android 12–14, keyboard behavior varies significantly by OEM:

Heights are percentage-based, not pixel-stable
Gesture navigation dynamically alters safe areas
Floating and split keyboards introduce transient viewports

React Native receives incomplete or rapidly changing inset information, making consistent keyboard avoidance mathematically unreliable.

4. Nested, stateful scroll containers amplify the problem

Most production forms are embedded inside:

Bottom sheets
Modals
Tab navigators
Collapsible or animated headers

These containers continuously mutate their layout constraints. Auto-scroll and focus calculations depend on deterministic container heights—conditions that no longer exist in deeply composed UI trees.

All this means classic keyboard handling methods break on multi-layered screens.

Example Problem Scenario (What Actually Happens)

You have a complex screen with a header, multi-section form inputs, a bottom CTA, all inside a ScrollView and wrapped inside a navigation stack.

When the user taps the last input:

The input jumps upward suddenly, OR
Gets partially hidden, OR
ScrollView auto-scrolls too late, OR
The keyboard overlaps your crucial bottom CTA button.

This is the reality of real-world apps, especially those built on the modern Expo/new architecture.

The Modern Solution Stack (Production-Proven)

These are the modern, recommended approaches that actually fix the issue in today's React Native architecture.

Solution 1 — Native Keyboard Synchronization with KeyboardProvider (react-native-keyboard-controller 1.20.x)

Modern React Native apps fail at keyboard handling not because of incorrect offsets or missing props, but because keyboard animations and layout updates are not synchronized at the native level.

react-native-keyboard-controller addresses this root cause by coordinating keyboard state, animation timing, and layout updates directly in native code.

Recommended Integration: Root-Level KeyboardProvider

The primary integration point is KeyboardProvider, which enables native keyboard synchronization across the entire application.

import { KeyboardProvider } from "react-native-keyboard-controller";
export default function App() {
  return (
    <KeyboardProvider>
      <RootNavigator />
    </KeyboardProvider>
  );
}

This enables native keyboard coordination for the entire app.

Scoped Keyboard Handling with KeyboardControllerView

KeyboardControllerView is an internal building block used by KeyboardProvider.

It should only be used when keyboard coordination must be explicitly scoped to a specific layout subtree.

Typical use cases include:

Forms inside modals or bottom sheets
Screens where only a portion of the UI should respond to keyboard movement
Preventing unnecessary re-layout of non-interactive UI

Why is it better

Computes keyboard height precisely
Works flawlessly with bottom sheets, tabs, and modals.
Better on Android 12–14
No layout jumps
Supports concurrent rendering

Runtime Control with useKeyboardController

useKeyboardController is a hook that gives access to the state of the react-native-keyboard-controller library. It returns two values:

enabled - a boolean value which indicates whether the library is enabled in the app;
setEnabled - a function that changes the state of the enabled property.

This hook is used only to enable or disable the native keyboard controller—primarily for gradual Android integration or fallback to adjustResize behavior when required.

Solution 2 — Native-Friendly Scroll Containers (Reanimated 3.10+, FlashList 1.7.x)

Keyboard issues on complex screens often occur when scroll position and keyboard movement are driven by JavaScript.

This causes delayed measurements and visible layout jumps during focus transitions.

To remove JavaScript from the critical layout path, use scroll containers that integrate cleanly with native animation timing:

Animated.ScrollView (Reanimated) for small, controlled layouts
FlashList for long, dynamic, or virtualized content

Both integrate better with native-driven keyboard animations.

Reanimated ScrollView Example:

<Animated.ScrollView
  keyboardShouldPersistTaps="handled"
  contentContainerStyle={{ paddingBottom: keyboardHeight }}
>
{children}
</Animated.ScrollView>

FlashList Example:

import { FlashList } from "@shopify/flash-list";
<FlashList
  data={data}
  estimatedItemSize={80}
  keyboardShouldPersistTaps="handled"
  contentContainerStyle={{
    paddingBottom: keyboardHeight,
  }}
  renderItem={renderItem}
/>

Solution 3 — If You Use Bottom Sheets (Reanimated / Gorhom)

Bottom sheets introduce an additional animated layer that can conflict with keyboard transitions and scrolling.

Without careful configuration, this often results in keyboard bounce, input focus jumps, or unstable drag behavior.

Bottom Sheet Gesture Configuration

Disable content panning only when:

The bottom sheet contains multiple text inputs
Nested scroll views compete with drag gestures
Keyboard interaction feels jumpy or unstable

enableContentPanningGesture={false}

Android Keyboard Mode

Use this only as a fallback when relying on the default Android window resizing behavior.

Forcing adjustResize can reintroduce layout jumps if combined with native keyboard synchronization.

android_keyboardInputMode="adjustResize"

Solution 4 — Use useWindowDimensions() Instead of Static Screen Height

Keyboard and screen size changes often break layouts that rely on static dimensions:

The problem:

Dimensions.get('window') is static
It does not update when the keyboard appears, the screen rotates, or the device enters split-screen
Any layout based on this value may be clipped, overlapped by the keyboard, or cause scroll jumps

Use this:

const { height } = useWindowDimensions();

It adapts when the keyboard reduces available height dynamically.

Solution 5 — Use KeyboardAwareScrollView for Automatic Input Scrolling

When your form contains multiple inputs, simply preventing layout jumps is often not enough.

You also want the focused input to scroll into view automatically.

react-native-keyboard-aware-scroll-view handles this efficiently.

Why This Works

Automatically scrolls the focused input above the keyboard
Works with nested forms and long lists
Supports Android and iOS, including safe handling of bottom tabs
Integrates well with native keyboard controllers (like react-native-keyboard-controller)
Minimal setup — reduces boilerplate scroll logic

Practical Real-World Implementation (Full Code Example)

This is a rock-solid implementation used in production onboarding flows:

import { KeyboardAwareScrollView, useKeyboardState } from "react-native-keyboard-controller";
import { TextInput, View } from "react-native";

export default function RegistrationForm() {
const keyboardHeight = useKeyboardState((state) => state.height);
return (
    <KeyboardAwareScrollView
      contentContainerStyle={{ paddingBottom: keyboardHeight + 20 }}
      bottomOffset={50} // optional offset for bottom CTA buttons
      keyboardShouldPersistTaps="handled"
    >
      <InputField />
      <InputField />
      <InputField />
    </KeyboardAwareScrollView>
  );
}
function InputField() {
  return (
    <TextInput
      style={{
        borderWidth: 1,
        marginVertical: 12,
        padding: 12,
        borderRadius: 8,
      }}
    />
  );
}

This handles:

iOS + Android
Gesture navigation
Variable keyboards
Concurrent rendering
ScrollView-based layouts
Bottom CTA buttons

ALL without layout jumps.

Debugging Checklist (What To Test Before Shipping)

Test split-screen mode on Android

Your input may be hidden due to reduced viewport height.

Test floating keyboard mode

TikTok/Samsung keyboards break height assumptions.

Test device rotation

Keyboard height changes drastically in landscape.

Test inside modals & bottom sheets

Most keyboard bugs occur inside nested containers.

Measure layout flicker using this:

adb logcat | grep "keyboard"

adb logcat → streams real-time Android system logs

grep "keyboard" → filters logs related to keyboard / IME events

What you will see

Logs like:

Keyboard show/hide events
IME height changes
Window resize calls
Focus changes

Why this matters

If you see:

Multiple keyboard show/hide events for one input focus
Rapid resize → unresize cycles
Keyboard height changing more than once

That's the root cause of flicker/bounce.

or for iOS:

xcrun simctl spawn booted log stream --level debug | grep "keyboard"

What this does

Streams iOS system logs from the Simulator
Filters keyboard-related notifications

What you'll see

UIKeyboardWillShow
UIKeyboardDidShow
Frame and height updates
Animation duration mismatches

Why this matters

If:

WillShow fires multiple times
Keyboard frame changes mid-animation

Your layout is reacting out of sync with the keyboard.

Conclusion: Keyboard Handling in Modern React Native Requires a New Approach

The assumptions behind KeyboardAvoidingView no longer hold up for modern React Native applications that rely on:

Concurrent rendering
react-native-screens
Bottom sheets and modals
The new architecture and Hermes
Deeply layered, animated UIs

In these environments, keyboard behavior becomes a cross-cutting concern, involving layout measurement, animation timing, gesture handling, and native window resizing.

To build reliable, input-heavy screens, production apps increasingly rely on a combination of:

Native keyboard synchronization (react-native-keyboard-controller)
Reanimated or FlashList-based scrolling
Dynamic keyboard height handling
Scroll-to-focused-input utilities
Intentional layout stabilization techniques

This layered approach reflects how high-quality production apps—including financial, social, and AI-driven products—handle keyboard interactions today.

This article was originally published on the GeekyAnts blog.

Your Vibe Code Has No Memory. DESIGN.md Fixes That.

GeekyAnts Inc — Fri, 03 Jul 2026 05:13:24 +0000

A single Markdown file called DESIGN.md gives your AI agent the design memory it lacks — keeping your UI consistent across every session.

Every session, your AI agent starts fresh. It picks generic colors, invents its own spacing, and drifts further from your actual UI. One Markdown file ends that.

Vibe coding works. You describe a feature, the AI builds it, you ship faster than ever. But spend a week on a product and you notice something: the button on page three uses a different blue than page one. The card padding is inconsistent. The font size on the new modal does not match anything else.

The AI did not forget. It never knew. Every prompt starts from zero.

This is the actual problem with vibe coding — not the code quality, not hallucinations, not even bugs. It is the drift. Session by session, page by page, the UI quietly loses coherence.

DESIGN.md is the fix. And paired with Google Stitch and Claude Code, it is quickly becoming the standard way serious builders approach AI-assisted frontend work.

What DESIGN.md actually is

It is a plain Markdown file. No proprietary format, no JSON schema, no Figma plugin required. You drop it in the root of your repo, and every AI agent that reads your project now knows your color palette, your type scale, your spacing system, your component rules.

A basic one looks like this:

# Design System

## Colors
- Primary: #1A73E8
- Background: #F8F9FA
- Text: #1F2937

## Typography
- Font: Inter, sans-serif
- H1: 32px / 500 weight
- Body: 16px / 400 weight

## Spacing
- Base unit: 8px
- sm: 8px, md: 16px, lg: 32px

## Components
- Button (primary): blue bg, white text, 4px radius
- Input: light gray border, 12px radius, focus outline

That is it. No tooling to install. Markdown is what LLMs read best — structured enough to parse, open enough to extend.

The file is not a design system tool. It is a design system memory. It tells the agent what decisions you already made so it stops inventing its own.

Where Google Stitch comes in

The blank-page problem with DESIGN.md is that you still have to write it in the first place.

Google Stitch solves this. It is an AI design tool from Google Labs that takes a natural language prompt — "dark SaaS dashboard, clean, muted greens" — and generates a full UI design. More importantly, it exports a DESIGN.md alongside the visual output.

So instead of writing the spec, you generate it. You explore in Stitch, pick a direction that feels right, and walk away with a Markdown file that encodes every visual decision that went into that design: the exact hex values, the type scale, the component patterns.

For most teams getting started, the file-based export is simpler; the MCP route is useful when you are actively iterating and want the code agent to stay in sync automatically.

Where Claude Code picks it up

Claude Code reads your repo. It picks up CLAUDE.md at the start of every session as a persistent instruction file — a place to write rules the agent follows across every run.

Add this to your CLAUDE.md:

## Design System
This project uses design.md at the project root.
Always refer to it when generating or modifying UI.
- Use only colors, fonts, and spacing from design.md.
- Do not introduce new values or defaults.
- Follow the component rules exactly.

Now when you ask Claude Code to build a settings page or refactor a button, it does not guess. It reads DESIGN.md, finds the primary color, finds the button spec, and generates code that matches what already exists in your product.

The UI does not drift because the agent no longer starts from zero — it starts from your spec.

The workflow, step by step

Explore in Stitch. Describe your UI in natural language. Iterate on a few directions using Stitch's redesign tools until the look feels right.
Export DESIGN.md. Download the design file. Review it — adjust token names, add platform-specific notes, remove anything irrelevant. Treat it as a proposal, not a final truth.
Commit it to the repo. Drop DESIGN.md at the project root alongside CLAUDE.md. It is now version-controlled. Changes go through your normal PR process.
Instruct Claude Code. Reference DESIGN.md in your CLAUDE.md. From this point, every UI task Claude Code runs stays within your defined system.
Build and iterate. Add pages, components, and flows with natural language prompts. When the design evolves, update DESIGN.md first — the agent inherits the change on the next run.

Why this changes how vibe coding works

Vibe coding without DESIGN.md is fast but brittle. Every new session is a coin flip on whether the AI remembers your visual language. With DESIGN.md, the spec is always in context. Different contributors, different sessions, different prompts — they all produce UIs that share the same tokens.

The AI has constraints, and it works within them.

There is also a practical benefit beyond consistency: less rework. The biggest time sink in vibe coding is not writing prompts — it is fixing the output. "Change this blue to our brand blue." "Make the padding consistent." "Why does this button look different from the one on the home page?" DESIGN.md cuts that loop significantly. The first pass is much closer to correct.

And because DESIGN.md lives in version control, your design decisions are auditable. You can diff them, review them in PRs, and roll them back. Design intent stops living in chat history and starts living in code.

What it does not fix

Budget some time to clean up what it exports.

The agent still drifts occasionally. A large or ambiguous DESIGN.md gives Claude less to anchor to. Keep it focused — under 200 lines if possible. Specificity beats completeness.

It does not handle everything that design actually involves.

Format fragmentation is real. Different tools structure DESIGN.md differently. Until something like a common token schema emerges, expect to normalize the file when switching between tools.

Start today

You do not need to overhaul your workflow to try this. Pick one project. Open Stitch, generate a UI direction you like, and export the DESIGN.md. Drop it in your repo. Add three lines to your CLAUDE.md pointing at it. Then ask Claude Code to build your next component and watch what changes.

Add this to your CLAUDE.md:

The stack: design.md (the spec) + CLAUDE.md (the instruction) + Claude Code (the agent).

Stitch handles the blank page. DESIGN.md handles the memory. Claude Code handles the build.

That is the workflow. It is not complicated. It just works better than prompting from zero every time.

This article was originally published on the GeekyAnts Blog.

Building a Resilient Hybrid-Cloud Network with WireGuard HA, Route-Based Failover, and Deep Observability

GeekyAnts Inc — Wed, 01 Jul 2026 12:49:17 +0000

Most hybrid-cloud networking discussions eventually converge toward the same set of enterprise-heavy solutions:

Managed VPN gateways
MPLS connectivity
Transit Gateway
BGP-based active-active architectures

In practice, many engineering teams are solving a much narrower — but operationally critical — problem:

Public cloud applications need reliable, secure access to private on-premises systems without introducing unnecessary networking complexity.

In our case, the requirement initially looked deceptively simple.

We had:

Public-facing APIs running on AWS
Internal APIs and databases hosted on-premises
Strict requirements around resilience and observability
A need to avoid expensive enterprise networking stacks

As traffic increased and failover testing became more realistic, several problems started emerging:

Tunnel health appeared healthy while application traffic silently failed
Intermittent packet forwarding issues became difficult to diagnose
Failover behavior became inconsistent
Route ambiguity started appearing during dual-path testing
Monitoring produced false-positive tunnel health

The problem slowly stopped being: "How do we create secure connectivity?" and became: "How do we build predictable, observable, and operationally recoverable hybrid-cloud networking?"

That distinction ended up shaping the entire architecture.

Instead of optimizing for networking sophistication, the final system intentionally optimized for:

Deterministic failover
Operational simplicity
Infrastructure-driven recovery
Deep packet-forwarding visibility
Cloud-agnostic portability

The result was a lightweight hybrid-cloud architecture built using WireGuard, Linux-native routing, AWS Route Table failover, Prometheus observability, and active-standby tunnel paths.

The Initial Assumption: One Tunnel Is Enough

The earliest implementation used a single WireGuard tunnel between AWS and the on-premises environment.

At small scale, this worked well — latency stayed low, operational overhead was minimal, and the architecture remained easy to reason about.

However, failover testing immediately exposed an operational weakness: the tunnel itself became a single recovery dependency.

Any degradation introduced:

Backend API timeouts
Intermittent request failures
Delayed recovery
Manual operational intervention

At this stage, the tunnel was technically functional, but operationally fragile.

Why Traditional Enterprise Networking Was Avoided

The obvious next step was evaluating managed VPN services, Transit Gateway, BGP-based routing, and active-active tunnel fabrics. On paper, these architectures looked attractive. Operationally, they introduced several concerns.

Concern	Operational Impact
Managed VPN pricing	Difficult to justify at mid-scale
Dynamic route convergence	Harder to predict during failures
Vendor abstractions	Reduced debugging visibility
Active-active routing	Increased troubleshooting complexity
BGP failover behavior	Operationally non-deterministic

One operational realization became increasingly clear: faster troubleshooting was consistently more valuable than maximizing tunnel utilization efficiency. At mid-scale, operational determinism mattered more than networking elegance.

Early Active-Active Experiments Created More Problems Than They Solved

The next iteration experimented with dual active tunnels. The idea initially seemed straightforward: two active paths, traffic balancing, higher availability, improved utilization.

Operationally, this introduced several difficult behaviors. During partial degradation testing, we observed:

Asymmetric return traffic
Intermittent packet forwarding failures
Route ambiguity inside Linux routing tables
Inconsistent failover timing
Hard-to-debug intermittent API failures

One particularly difficult issue appeared when outbound and return traffic took different paths during transient failures. From the application perspective, some requests succeeded while others silently timed out — even though tunnel interfaces still appeared healthy.

The architecture technically achieved redundancy. Operationally, it reduced predictability.

Eventually, the team realized: deterministic failover behavior was more operationally valuable than active-active utilization efficiency. That became the turning point in the architecture.

Moving Toward Deterministic Routing

Instead of active-active routing, the architecture evolved toward isolated tunnel paths, active-standby failover, infrastructure-driven recovery, and strict subnet separation.

Traffic would always prefer a primary path and shift only during validated degradation. This dramatically simplified troubleshooting, observability, routing behavior, and operational recovery.

The system intentionally sacrificed maximum tunnel utilization and dynamic traffic balancing in exchange for deterministic failover, operational transparency, and predictable recovery.

Final Hybrid-Cloud Architecture

The final design used two completely isolated WireGuard paths, dedicated subnet ownership, AWS Route Table failover, and infrastructure-level recovery automation.

Why Two Completely Separate Tunnel Paths Worked Better

Operationally, shared tunnel systems introduced several recurring problems: overlapping route ownership, shared interface state, route recursion issues, asymmetric forwarding, and failover race conditions.

Instead, each tunnel path operated independently with isolated interfaces, isolated route ownership, isolated health validation, and isolated failover behavior. Failures became easier to isolate, observe, and recover from.

The secondary path remained continuously available but did not actively serve traffic until route failover occurred — a lightweight HA model without requiring BGP convergence, mesh synchronization, or overlay routing complexity.

Why Subnet Isolation Became Critical

Each tunnel path owned an isolated subnet slice.

Environment	Interface	Tunnel IP	Role
On-Premises	wg0 / wg1	10.100.0.2 / 10.200.0.2	Core Plane
AWS Primary	wg0	10.100.0.1	ACTIVE
AWS Secondary	wg1	10.200.0.1	STANDBY

One operational lesson became very clear: simpler routing topologies fail in more understandable ways.

Separating VPN Edges from Backend Systems

Separating VPN edge gateways from backend APIs, databases, and public ingress layers reduced routing recursion, asymmetric local forwarding, interface overlap, and expanded blast radius — while improving maintenance flexibility, backend isolation, and operational scaling independence.

The Biggest Monitoring Mistake We Initially Made

Early monitoring focused primarily on interface UP state and WireGuard handshake timestamps.

During testing, we observed tunnels remaining "healthy" from WireGuard's perspective while real application traffic silently failed. In several cases, handshake timestamps continued updating and interfaces remained UP — but packet forwarding had already degraded.

One particularly difficult debugging session involved intermittent API failures where ICMP occasionally worked, application traffic intermittently timed out, and tunnel interfaces remained healthy. The root issue turned out to be partial packet-forwarding degradation rather than tunnel failure itself.

That incident fundamentally changed the monitoring strategy.

Evolving Toward Data-Plane Validation

The monitoring model evolved into three distinct validation layers.

Validation Layer	Purpose
Interface Validation	Verify interface availability
Handshake Validation	Verify cryptographic synchronization
Data Plane Validation	Verify actual packet forwarding

Production Health Validation Script

Tunnel health metrics were exported using a lightweight Linux validation script integrated into the Node Exporter textfile collector.

#!/bin/bash

METRIC_FILE="/var/lib/node_exporter/textfile_collector/wg.prom"
WG_INTERFACE="wg0"
WG_PEER_IP="10.100.0.1"
THRESHOLD_SECONDS=180

if ! wg show $WG_INTERFACE >/dev/null 2>&1; then
    echo "wireguard_wg0_healthy 0" > "$METRIC_FILE"
    exit 0
fi

NOW=$(date +%s)
LAST=$(wg show $WG_INTERFACE latest-handshakes | awk '{print $2}')

if [ -z "$LAST" ] || [ "$LAST" = "0" ]; then
    echo "wireguard_wg0_healthy 0" > "$METRIC_FILE"
    exit 0
fi

DIFF=$((NOW - LAST))

if [ $DIFF -gt $THRESHOLD_SECONDS ]; then
    echo "wireguard_wg0_healthy 0" > "$METRIC_FILE"
    exit 0
fi

if ! ping -c 2 -W 2 $WG_PEER_IP >/dev/null 2>&1; then
    echo "wireguard_wg0_healthy 0" > "$METRIC_FILE"
    exit 0
fi

echo "wireguard_wg0_healthy 1" > "$METRIC_FILE"

The monitoring flow validated interface state, handshake freshness, and actual packet forwarding.

That final packet-forwarding validation ended up becoming the most operationally valuable signal in the system.

Prometheus Observability Pipeline

graph LR

    Script[Health Validation Script]
        -->|Writes Metrics| File["wg.prom"]

    NodeExporter[Node Exporter]
        -->|Expose Metrics| Prometheus[Prometheus]

    Prometheus
        --> Alertmanager[Alertmanager]

    Alertmanager
        --> Automation[Failover Automation]

    Automation
        --> AWSRT[AWS Route Tables]

Infrastructure-Driven Failover

Instead of rebuilding tunnels or restarting applications during failures, failover occurred entirely through AWS Route Table updates.

When the primary tunnel degraded:

Prometheus detected failure
Alertmanager triggered automation
Route targets were updated
Traffic shifted to the standby WireGuard node

During testing, primary degradation was typically detected within seconds, route updates remained operationally predictable, and recovery became significantly more deterministic compared to earlier active-active experiments.

One operational pattern became consistently clear: the less failover logic applications contained, the more predictable recovery became.

Why This Architecture Worked Operationally

Operational Simplicity

The final design intentionally avoided BGP convergence, overlay routing complexity, active-active synchronization, and enterprise VPN orchestration. Everything relied on Linux routing, lightweight EC2 instances, WireGuard, and route-table automation — which significantly reduced operational overhead.

Better Failure Isolation

Separating tunnel paths, subnet ownership, route ownership, and backend systems made failures significantly easier to isolate, debug, and recover from.

Observability Became More Valuable Than Redundancy Alone

Redundant tunnels without packet-forwarding visibility still create operational risk. The architecture became reliable not simply because of redundancy, but because degradation became observable.

Cloud-Agnostic Portability

Because the architecture depended primarily on WireGuard, Linux-native routing, Prometheus, and infrastructure automation, the same design could be replicated across AWS, Azure, Google Cloud, private cloud environments, and bare-metal infrastructure with minimal architectural changes.

Final Thoughts

This architecture reinforced several operational principles repeatedly throughout testing.

First: Simpler networking topologies are easier to recover from during real incidents.

Second: Deterministic failover is often operationally more valuable than maximizing tunnel utilization.

And finally: Observability matters more than redundancy alone.

Using WireGuard, Linux-native routing, Prometheus observability, and AWS Route Table automation, it was possible to build resilient hybrid-cloud connectivity, predictable failover behavior, observable tunnel infrastructure, and cloud-agnostic deployment patterns — without introducing unnecessary enterprise networking complexity.

Originally published on the GeekyAnts Blog.

Cloud-Native and Cloud-Agnostic Are Not Ideologies; They Are Business-Stage Decisions

GeekyAnts Inc — Thu, 25 Jun 2026 06:38:02 +0000

One of the biggest problems in modern DevOps is that the industry often romanticizes scalability long before organizations develop the operational maturity required to support it.

Startups deploy Kubernetes before achieving product-market fit.
Engineering leadership demands "future-proof" architecture before deployment consistency even exists.
Teams design for multi-region scale while basic observability, rollback strategy, and operational ownership remain undefined.

A surprising amount of "platform engineering" today is simply premature complexity with better branding.

And yet the opposite problem exists too. Organizations that optimize aggressively for short-term delivery speed often discover later that those same infrastructure choices now limit enterprise onboarding, regional expansion, governance, or operational flexibility.

The problem is not cloud-native vs. cloud-agnostic. The real problem is treating infrastructure strategy as an ideological decision instead of a business-stage decision.

Infrastructure Strategy Is Often a GTM Strategy

Infrastructure decisions directly influence go-to-market speed.

A startup trying to validate product-market fit is optimizing for release velocity, fast experimentation, lean operational overhead, and developer productivity. In that environment, cloud-native infrastructure is often the rational choice. Managed databases, serverless execution, provider-native IAM, CDN ecosystems, and integrated observability dramatically reduce operational burden. A small engineering team can move incredibly fast by leveraging managed cloud ecosystems instead of building operational layers internally.

In early-stage companies, speed matters more than theoretical portability — because early-stage companies are not optimizing for infrastructure independence. They are optimizing for survival.

This is where many infrastructure discussions lose context. The industry often frames cloud-native adoption as architectural compromise, when in reality it is frequently the fastest path to GTM execution.

For example:

A startup validating product-market fit may choose Firebase, Lambda, or DynamoDB because operational simplicity matters more than portability.
A small SaaS company may rely heavily on AWS-native observability and IAM because maintaining internal platform tooling would slow product delivery.
A lean engineering team may intentionally avoid Kubernetes early because operational ownership would consume too much engineering bandwidth.

None of these are bad decisions. In fact, they are often the correct decisions for that stage of the business.

But GTM Priorities Eventually Change

The architecture that accelerates early growth is rarely the same architecture that supports long-term operational evolution.

As organizations mature, infrastructure priorities begin shifting toward enterprise onboarding, compliance requirements, regional expansion, customer-hosted deployments, operational standardization, cost governance, and cross-team coordination.

This is where many companies discover that infrastructure decisions made during the GTM phase quietly become long-term operational assumptions. For example:

A SaaS platform built heavily around AWS-native services may later struggle when enterprise customers require customer-hosted deployments.
A company optimized around single-region cloud-native architecture may face operational friction when expanding into regulated geographies with data residency requirements.
A growing engineering organization may discover that deployment workflows built for one small team no longer scale across multiple product squads.

The problem is not that the original decisions were wrong. The problem is assuming they remain optimal forever. Infrastructure decisions often outlive the stage of the business they were designed for.

When Should Prototype Architecture Evolve?

One of the biggest misconceptions in infrastructure strategy is assuming scalability concerns should dominate from day one. In reality, most organizations should not optimize heavily for portability, multi-region architecture, or platform abstraction during the prototype phase.

But there are signals that the infrastructure strategy needs to evolve. That transition usually begins when:

revenue-generating customers appear,
uptime commitments become contractual,
on-call rotations become operationally painful,
multiple engineering teams begin contributing simultaneously,
compliance requirements emerge, or
enterprise customers introduce deployment constraints.

This is often the point where prototype architecture starts becoming production architecture — and where many organizations struggle. Some continue operating startup-grade infrastructure long after the business has outgrown it. Others introduce enterprise-scale complexity far too early. Both create friction, just at different stages of maturity.

Cloud-Agnostic Thinking Becomes More Valuable Over Time

One of the biggest misconceptions in platform engineering is assuming cloud-native and cloud-agnostic are opposing philosophies. Mature infrastructure strategies often combine both.

Cloud-native acceleration can coexist with cloud-agnostic operational patterns. For example, CI/CD workflows can remain portable, observability can stay unified, workloads can remain containerized, and deployment patterns can stay provider-independent — all while selectively using provider-native services where they provide meaningful leverage.

This is where cloud-agnostic thinking becomes strategically valuable. Not because portability itself is the goal, but because operational flexibility becomes increasingly important as organizations scale. For example:

Enterprise customers may require hybrid deployments.
Regulated industries may introduce region-specific infrastructure constraints.
Multi-cloud operational visibility may become necessary after acquisitions or expansion.
Customer-hosted environments may require standardized deployment models outside the original cloud ecosystem.

The strongest infrastructure strategies are usually not fully cloud-native or fully cloud-agnostic. They evolve intentionally as business requirements evolve.

Portability Has an Operational Cost Too

Portability is often discussed as freedom. What gets discussed less frequently is the operational cost required to maintain it.

Portable systems typically introduce additional abstraction layers, broader platform engineering responsibility, stronger standardization requirements, self-managed tooling, and significantly higher operational maturity expectations.

Running PostgreSQL inside Kubernetes improves portability. It also transfers failover ownership, backup management, patching responsibility, storage reliability, and operational risk directly onto the engineering organization.

Similarly, organizations pursuing aggressive multi-cloud strategies often underestimate the operational duplication introduced across IAM models, networking controls, observability pipelines, Terraform abstractions, security posture management, CI/CD orchestration, and cloud-specific operational edge cases.

Many multi-cloud initiatives fail not because of infrastructure limitations, but because organizational maturity never caught up with architectural ambition. The industry talks heavily about avoiding vendor lock-in. It talks far less about the operational ownership required to replace what managed ecosystems already solved.

The Hardest Scaling Problem Is Usually Coordination

One of the clearest patterns across growing engineering organizations is that infrastructure complexity scales faster than operational clarity.

The hardest scaling problem in many companies is no longer compute — it is coordination. As engineering organizations grow, ownership boundaries blur, deployment consistency drifts, observability becomes fragmented, operational tribal knowledge increases, and infrastructure decisions made by small teams become inherited organizational constraints.

This is why modern DevOps is increasingly less about tooling and increasingly more about organizational scalability. The conversations are shifting toward operational consistency, governance, reusable workflows, platform standardization, developer enablement, and reducing the future cost of change.

Because eventually every growing organization discovers the same thing: scaling infrastructure is relatively easy. Scaling operational consistency is not.

Final Thought

Perhaps the biggest infrastructure mistake modern engineering organizations make is not choosing the wrong cloud strategy — it is solving for the wrong stage of the business.

A startup struggling to achieve product-market fit does not have the same operational priorities as an enterprise platform operating across regions, compliance boundaries, and customer-hosted environments. Yet the industry often treats infrastructure decisions as ideological commitments instead of evolving business-stage strategies.

Cloud-native and cloud-agnostic architectures are not opposing belief systems. They are tools. And the real challenge is recognizing when the business has evolved enough that the infrastructure strategy must evolve with it.

Because the architecture that accelerates go-to-market is rarely the same architecture that optimizes long-term operational flexibility. The strongest platforms are not the ones that predict the future perfectly. They are the ones designed to evolve before the business outgrows them.

Originally published on the GeekyAnts blog.

We Built a 114-Second AWS-to-Azure Failover. Here's What We Learned

GeekyAnts Inc — Thu, 25 Jun 2026 06:20:37 +0000

A practical guide to building a 114-second multi-cloud disaster recovery failover between AWS and Azure — what we built, what broke, and what we learned.

Cloud outages are no longer rare edge cases.

AWS has had seven major incidents since 2021. Azure has had its share too. And every time, the story splits in two: teams with tested DR plans treated it as an operational issue. Teams without them made infrastructure decisions in the middle of production downtime.

The most visible example came from the December 2021 AWS us-east-1 outage. Slack went down. McDonald's mobile ordering collapsed. Even some of Amazon's own internal systems were affected.

But the interesting part wasn't the outage itself.

It was how differently companies experienced it.

We decided to be the first kind of team. This is what we built, what broke, and what we'd do differently.

Why Single-Cloud Is Still a Risk

AWS, Azure, and GCP publish SLAs that look reassuring on paper. AWS EC2 targets 99.99% uptime — roughly 52 minutes of downtime per year.

That sounds fine until you realize production outages rarely happen because a single service disappears completely. They happen because of networking issues, IAM failures, degraded DNS, control plane problems — things that make your application unavailable while the provider technically considers it "running."

And timing matters more than percentages. A short outage at 3am is a footnote. The same outage during a product launch or payment cycle is a very different business problem.

SLA credits don't solve that. Lost transactions, incident response fatigue, customer trust erosion — these cost far more than the infrastructure bill.

That's why DR is ultimately less about redundancy and more about business risk.

What We Built

Architecture overview of the AWS EKS → Azure AKS warm standby disaster recovery setup with PostgreSQL streaming replication and Route 53 failover routing.

Our setup:

AWS EKS — primary cluster, serving all production traffic
Azure AKS — warm standby, nodes running but pods scaled to zero
PostgreSQL 16 streaming replication — Azure DB always in sync, zero lag
Route 53 failover routing — DNS switches automatically when AWS goes unhealthy

The standby cluster runs at roughly 18% of the primary cost. Full DR capability at 18 cents per primary dollar.

The entire failover — database promotion, Kubernetes rollout, DNS switching, smoke tests — averaged 114 seconds during drills.

We didn't get there on the first try.

The DR Maturity Ladder

Before getting into what broke, it's worth being honest about where most teams actually sit:

Level 0 — Recovery depends entirely on people figuring things out during the incident. Backups exist somewhere, probably.

Level 1 — Backups exist and can be restored. Slow, stressful, but survivable.

Level 2 — Cold standby. Infrastructure exists elsewhere but isn't running. Expect hours of recovery time.

Level 3 — Warm standby. Infrastructure running, workloads at zero, replication active. This is what we built. Recovery in minutes, not hours.

Level 4 — Hot standby. Secondary environment fully live, failover is purely a routing event.

Level 5 — Active-active. Both clouds serve traffic simultaneously. Powerful, but expensive and operationally complex. Most teams don't need this.

Most organizations sit between Level 0 and Level 2 and think they're at Level 3. The drills are what reveal the truth.

What Actually Broke

The first drill took 35 minutes and failed in three places. That ended up being the most valuable part of the project.

PostgreSQL promotion timing

We promoted the Azure replica and immediately started scaling AKS pods. Sometimes it worked. Sometimes PostgreSQL was technically promoted but not yet accepting connections.

Pods would start healthy. Database connections would fail silently. It looked random. It wasn't.

The issue: we assumed promotion completion and connection readiness happened at the same time. They don't.

Fix: replace sleep 5 with polling:

> [Original source code block — not preserved by the page's renderer.
> Paste the polling script from the original article here before publishing:
> https://geekyants.com/blog/we-built-a-114-second-aws-to-azure-failover-heres-what-we-learned ]

Don't move on until the database confirms it's ready. That single change removed most of the inconsistent failover behavior.

The circular DNS dependency

This one cost us days.

Our Route 53 health check pointed at api.nagacharan.store. During a drill, when DNS switched to Azure, the health check started getting 200 OK — from Azure. Route 53 concluded AWS was healthy and switched DNS back to AWS. Which had no pods running. Which failed the health check. Which switched back to Azure. Loop.

The fix: a dedicated subdomain that never participates in failover routing.

health.nagacharan.store → always points to AWS ALB (never changes)

Route 53 checks this every 30 seconds:

200 OK → PRIMARY healthy → serve AWS
503 → PRIMARY unhealthy → serve Azure

health.nagacharan.store is a plain alias to the ALB. It never gets swapped. No circular dependency. Ever.

The double-failover state

Run the failover script twice without running failback in between. PostgreSQL on Azure is already promoted. pg_promote() throws:

ERROR: recovery is not in progress

The script continues. Nothing works correctly.

One guard check at the start fixed this permanently:

> [Original source code block — not preserved by the page's renderer.
> Paste the guard-check snippet from the original article here before publishing.]

Sequence conflicts on failback

After multiple drill cycles, the PostgreSQL sequence on the newly-promoted instance falls behind the actual max ID. The next write throws a duplicate key violation.

Fix — one line, run before every write test:

> [Original source code block — not preserved by the page's renderer.
> Paste the sequence-fix one-liner from the original article here before publishing.]

Shell scripts that fail quietly

Early scripts continued execution after partial failures. A missing variable or failed command would let the workflow proceed and leave infrastructure in a broken intermediate state.

That's it. Failures became loud and early instead of silent and late. It sounds minor. It dramatically improved debugging.

The part most DR writeups skip

During the DR period, your application keeps writing data. New rows. Advanced sequences. Committed transactions.

When you fail back to AWS, your AWS database is stale.

Our failback script handles this explicitly:

# Export everything written to Azure during DR
> [Original source code block — not preserved by the page's renderer.
> Paste the failback export script from the original article here before publishing.]

Then rebuild streaming replication from scratch — pg_basebackup from AWS to Azure in 12 seconds. Azure is a replica again. The system is back to normal state.

No manual reconciliation. No data loss.

The numbers

Metric	Target	Achieved
Total RTO	60 minutes	114 seconds
DB promotion	–	12s
AKS pod startup	–	33s
DNS propagation	–	60–90s
RPO	5 minutes	0 seconds
Failback total	–	~3 minutes
DR cost vs primary	–	18%

The RPO of 0 comes from streaming replication. At the moment of failure, Azure has already applied every transaction AWS committed. The data is already there before the incident happens.

The progression across drills:

Drill	Time	Manual Fixes
1	~35 min	Multiple
2	~8 min	One
3	114 seconds	–

The difference wasn't better cloud infrastructure. It was fixing the assumptions that only reveal themselves when things break.

Why Multi-Cloud Over Multi-Region?

Multi-region inside AWS is genuinely better than single-region. But it still assumes AWS itself is operational.

Some failures don't respect regional boundaries: IAM outages, control plane failures, DNS disruptions, provider-wide networking issues. In those situations, us-west-2 doesn't help if us-east-1 is the symptom and IAM is the disease.

Multi-cloud also changes your negotiating position. When you can realistically move workloads, pricing conversations with providers get a lot more interesting.

What We'd Tell Teams Starting This Today

Start with a single non-critical workload. Get replication working. Automate a basic failover. Run drills until it's boring. That teaches more than months of architecture discussions.

Test failure intentionally. Most of the useful fixes came from deliberately breaking things — GameDays, controlled outages, introducing race conditions. The circular DNS bug only became obvious because we kept drilling until edge cases surfaced.

Monitor the standby continuously. The standby environment cannot be something teams only look at during outages. Replication lag, cluster health, DNS state — these should already be visible. The worst time to discover standby drift is during a production incident.

Automation is not the hard part. Trust is. Most teams still want a human involved before traffic moves between clouds during a real incident. That's probably healthy. Building trust in the process is what makes automated failover eventually feel safe.

The Bottom Line

Before this project, multi-cloud DR felt like something only very large organizations could operate.

After five drills, it felt achievable. Not easy. Achievable.

Most of the problems weren't exotic cloud infrastructure challenges. They were timing assumptions, sequencing gaps, incomplete automation, and replication edge cases. Solvable problems. Problems you can practice.

The 114-second failover didn't come from a single architectural insight.

It came from running the process until it broke, fixing what broke, and running it again.

Disaster recovery is less about having the right architecture and more about having a process your team actually trusts.

During a real incident, nobody reads the architecture diagram.

What matters is whether traffic recovers safely, whether data stays consistent, and whether the engineers running the recovery have done it enough times that it feels routine.

The best time to get there is before the outage forces the conversation.

Originally published on the GeekyAnts blog.

Locust Performance Testing

GeekyAnts Inc — Thu, 25 Jun 2026 05:29:47 +0000

What is Performance Testing?
Performance testing is a crucial aspect of software development that evaluates how an application behaves under various conditions and loads. It includes several types of testing, such as load testing, stress testing, and endurance testing. The goal is to ensure that the application performs well under expected and peak loads, providing a smooth user experience and maintaining reliability.

Locust
Why is Performance Testing Important?
Load testing is the process of simulating real-world user traffic on your application to see how it performs under pressure. It helps you:

Identify Bottlenecks: Discover which parts of your application (database queries, API endpoints, specific views) slow down under load.
Ensure Scalability: Understand how many concurrent users your current setup can handle and plan for growth.
Prevent Crashes: Find breaking points before your users do.
Improve User Experience: Ensure your app remains fast and responsive, even during peak times.
About Locust
Any application's performance must be evaluated and improved through load testing. We utilise it to assess whether our application can survive the demands of actual use. Locust is a potent tool in every developer's toolbox for efficient load testing. With this free, open-source Python programme, you can simulate millions of concurrent users and describe user behaviour using Python code. This article will serve as your comprehensive, example-filled guide to load testing using Locust.

What is a Locust?
Locust is a distributed, scalable, and user-friendly load testing tool. Simulating traffic patterns aids engineers in understanding how many concurrent users a system can support. The key benefit of using Python code to describe user behaviour is that Locust is extremely flexible and configurable.

Installing Locust
Ensure you have Python 3.6 or higher installed before installing Locust. Pip may then be used to install Locust:

pip install locust
Getting Started with Locust
You must provide user behaviour in a Python file to utilise Locust for the first time. The actions that the simulated users will take are listed in this file, which is sometimes called locustfile.py.

from locust import HttpUser, task, between

class MyUser(HttpUser):
wait_time = between(1, 3)

@task
def hello_world(self):
self.client.get("/")
In this illustration, the behaviour of a simulated user is defined by WebsiteUser. The homepage task is executed after the user has waited between 5 and 15 seconds (wait_time = between(5, 15)) and sends a GET request to the home page (self.client.get("/")).

Running a Locust Test
Navigate to the directory containing your locustfile.py and issue the locust command to conduct a Locust test:

locust -f sample.py
The web interface for Locust then launches, and its address is http://localhost:8089. Here, you can define the destination website, the total number of users to simulate, and the spawn rate.

Open http://localhost:8089
Locust web interface for Load testing
Provide the hostname of your server and try it out!

The following screenshots show what it might look like when running this test using 50 concurrent users, with a ramp-up rate of 1 user/s
Failed request and response time for Load testing results in Locust
Under the Charts tab, you’ll find things like requests per second (RPS), response times and number of running users:

Locust charts for RPS, response times, and number of users during load test.
Direct command line usage / headless
Using the Locust web UI is entirely optional. You can supply the load parameters on the command line and get reports on the results in text form:

locust --headless --users 10 --spawn-rate 1 -H http://your-server.com
[2021-07-24 10:41:10,947] .../INFO/locust.main: No run time limit set, use CTRL+C to interrupt.
[2021-07-24 10:41:10,947] .../INFO/locust.main: Starting Locust 2.37.12
[20
21-07-24 10:41:10,949] .../INFO/locust.runners: Ramping to 10 users using a 1.00 spawn rate

Name # reqs # fails | Avg Min Max Median | req/s failures/s

GET /hello 1 0(0.00%) | 115 115 115 115 | 0.00 0.00

GET /world 1 0(0.00%) | 119 119 119 119 | 0.00 0.00

Aggregated 2 0(0.00%) | 117 115 119 117 | 0.00 0.00

[2021-07-24 10:44:42,484] .../INFO/locust.runners: All users spawned: {"HelloWorldUser": 10} (10 total users)
More about running without a web UI

Key Differences Between Locust, K6, and JMeter
Performance Testing: Key Differences Between Locust, K6, and JMeter
Feature k6 Locust JMeter
Scripting language JavaScript Python GUI-based; optional Beanshell/Groovy scripting
Developer-Friendly Designed for developers with a clean API Highly flexible with python scripting Less developer-friendly; GUI-based with scripting as an add-on
GUI Interface CLI & Cloud/Grafana dashboards Web-based dashboard Full graphical UI
Real-Time Monitoring Grafana/Cloud integrations Built-in web UI Basic GUI reports; needs plugins for advanced monitoring
CI/CD Integration Native support for pipelines (GitHub Actions, Jenkins, etc.) Possible with scripts and tools Requires extra setup and plugins
Protocol Support HTTP/HTTPS (limited other protocol support) HTTP/HTTPS (extensible via Python) HTTP, FTP, JDBC, SOAP, JMS, and more
Custom Scenarios JavaScript-based flow control Python-based; excellent for complex logic Limited to GUI flows or custom scripts
Scalability Supports distributed & cloud testing Can simulate millions of users Scales with effort; memory-intensive
Resource Usage Lightweight Efficient, low hardware footprint Heavy memory usage on large tests
Performance Metrics Rich metrics, InfluxDB/Grafana integration Real-time metrics in the dashboard Basic by default; extensible with plugins
Distributed Testing Native support via k6 Cloud or output streaming Via worker nodes, easily configured Via remote servers, but requires configuration
Best Use Case API load testing, DevOps pipelines, scalable and scriptable load tests Scalable web app testing, custom behavior scripting Broad protocol support, functional + load testing, GUI-centric teams
Best Practices for Performance Testing
Define Clear Objectives: Establish what you want to achieve with performance testing, including setting benchmarks, understanding acceptable load thresholds, and identifying critical metrics.
Test in a Production-Like Environment: Conduct tests in an environment that closely mirrors your production setup to get accurate and actionable results.
Use Realistic Test Data: Utilize data that represents real-world usage patterns, including a mix of user types, transactions, and data sizes.
Automate Testing: Integrate performance testing into your CI/CD pipeline to catch performance regressions early and ensure every deployment is automatically tested.
Analyze and Act on Results: Collect and analyze performance data to identify bottlenecks and areas for improvement, optimizing your application and infrastructure accordingly.
Conclusion:
Locust is a versatile and powerful tool for load testing, offering flexibility through Python scripting and ease of use with its web-based interface. Whether you are stress testing a simple web application or a complex API, Locust provides the necessary tools to simulate real-world traffic and identify performance bottlenecks. Its scalability ensures that it can handle projects of any size, making it an essential tool in the arsenal of performance engineers.

By leveraging Locust, teams can proactively address performance issues, ensuring that their systems remain robust and responsive under peak loads.

tRPC in TypeScript: Simplify API Development Without Boilerplate

GeekyAnts Inc — Fri, 19 Jun 2026 11:00:30 +0000

For most developers, building an API means choosing between REST and GraphQL, setting up routes or resolvers, and managing a separate schema to keep the frontend and backend in sync. It's a familiar workflow, one that's been refined over the years with tools, conventions, and plenty of boilerplate.

But when working in a TypeScript-first codebase, especially one where you control both the client and server, this approach starts to feel unnecessarily heavy. You're writing types twice, wiring up handlers that mirror database functions, and dealing with schema drift that shouldn't exist in the first place.

This is the gap that tRPC fills. It doesn't try to replace REST or GraphQL everywhere, but it does challenge the idea that an API layer always needs to be a separate contract. By leaning fully into TypeScript's type system, tRPC offers a way to define backend procedures and instantly infer their types on the client without any code generation, schema stitching, or serialization layer in between.

The result is a lighter, more intuitive developer experience that feels like calling functions across files, not across a network.

The Boilerplate Problem

API development has always involved some level of duplication, especially when trying to keep the frontend and backend in sync. In a typical REST setup, you define your route on the server, write a handler, and then manually create a corresponding fetch call on the client. If you're using TypeScript, you'll probably also define the input and response types in a shared file or risk getting out of sync.

GraphQL improves this a bit by centralizing the schema, but now you're managing resolvers, schema definitions, codegen, and possibly another layer like Apollo or urql. You're still stitching together multiple parts just to send and receive a piece of data.

Take a simple example: creating a new user.

// server: REST route
app.post("/users", async (req, res) => {
  const { name, email } = req.body as { name: string; email: string };
  const user = await db.user.create({ data: { name, email } });
  res.json(user);
});

// client: manual fetch + duplicated types
type CreateUserInput = { name: string; email: string };
type CreateUserResponse = { id: string; name: string; email: string };

async function createUser(input: CreateUserInput): Promise<CreateUserResponse> {
  const res = await fetch("/users", {
    method: "POST",
    body: JSON.stringify(input),
  });
  return res.json();
}

Even in this basic flow, there's duplication in types, manual request handling, and room for drift. Change a field name on the server and forget to update the client? TypeScript won't catch it unless you're explicitly sharing types, which introduces its own overhead.

tRPC gets rid of this ceremony. You write a function once, on the server, and the client automatically understands how to call it, what inputs it expects, and what it returns. No manual fetch calls. No custom hooks. No syncing types.

How tRPC Works: A Mental Model

At its core, tRPC treats your backend like a collection of type-safe functions. Instead of defining endpoints or resolvers, you define procedures, which are functions that live inside routers. These routers group related logic together, and the entire structure can be consumed directly by the client, with full type safety.

A simple example looks like this:

// server: router with a procedure
import { z } from "zod";
import { router, publicProcedure } from "./trpc";

export const userRouter = router({
  getById: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      return db.user.findUnique({ where: { id: input.id } });
    }),
});

export const appRouter = router({
  user: userRouter,
});

export type AppRouter = typeof appRouter;

Here, getById is just a function. It receives input (validated using Zod), runs server-side logic, and returns a result. No need to declare a route or response type separately — everything is inferred from the function itself.

The real magic happens on the client. After defining your procedures and grouping them into routers, you create an appRouter, essentially a central object that represents your entire backend API. This is passed into the tRPC server handler (like in a Next.js API route or app handler), which exposes the procedure tree to the client. From there, the client can import a trpc instance and start calling these procedures directly, with full type safety out of the box.

// client: fully typed call, no manual types needed
const user = await trpc.user.getById.query({ id: "123" });

There's no need to define getById on the client, or manually specify its input/output types. tRPC knows exactly what this function expects, because it's inferred directly from the backend definition.

This model — "define it once, use it everywhere" — is what makes tRPC feel so different. It removes the artificial API boundary between server and client in projects where both are written in TypeScript. Instead of maintaining contracts, you're just calling strongly-typed functions.

It's not just about convenience; it's about removing entire categories of bugs that stem from type mismatches and outdated API definitions.

Simplifying the Stack with tRPC

tRPC works especially well in setups where the backend and frontend live in the same codebase, or at least speak the same language. That's why it's become a popular choice in full-stack TypeScript apps built with frameworks like Next.js, paired with an ORM like Drizzle for database access and React Query for frontend data fetching.

In these environments, tRPC doesn't just simplify API calls, it removes the need to even think about them as "API calls" in the traditional sense. You're just calling functions with inputs and getting typed results back, whether you're working in a backend file or a frontend component.

It also integrates cleanly with tools you're probably already using:

Next.js: tRPC can be wired up to API routes or used with server handlers, making it a natural fit for apps built on the App Router or Pages Router.
React Query: When paired with the @trpc/react-query adapter, procedures can be treated as fully type-safe queries or mutations — with caching, retries, and background refetching handled out of the box.
ORMs: Since most modern ORMs (like Prisma, Drizzle, or Kysely) support static typing, combining them with tRPC creates a fully type-safe path from your database to your UI without needing to define types or schemas more than once.

The benefit isn't just fewer lines of code, it's clearer boundaries, safer data flow, and faster iteration. When everything speaks TypeScript, from your database to your frontend, you're less likely to ship runtime bugs caused by broken contracts or outdated assumptions.

When tRPC Makes the Most Sense

Like most tools in the TypeScript ecosystem, tRPC isn't trying to solve everything for everyone — it's optimized for a specific kind of project.

tRPC shines when:

The frontend and backend are both written in TypeScript
The same team controls both ends of the stack
There's no need for public-facing APIs or multi-language support
Fast iteration, tight feedback loops, and strong type safety matter more than API versioning or schema generation

This makes it a great fit for:

Internal tools and admin dashboards
Full-stack TypeScript apps built with frameworks like Next.js
Rapid prototypes or early-stage products
Monorepos, where backend and frontend live in the same codebase

In these kinds of projects, tRPC often replaces traditional API layers with something that feels closer to function calls than network requests. You don't need to think about routes, schemas, or response formats — just write the logic and let TypeScript handle the rest.

But What About REST and GraphQL?

tRPC isn't trying to replace REST or GraphQL across the board, but it does challenge some long-held assumptions about how API layers should be built.

REST is still the default for many teams, largely because of its simplicity and ubiquity. It works well when you need predictable URLs, clear separation between resources, and broad tooling support. GraphQL, on the other hand, offers flexibility and strong typing, especially useful when dealing with complex relationships or multiple consumers querying the same data differently.

But both come with trade-offs — schemas to maintain, types to sync, code to generate, and sometimes extra layers that don't add much value when you're working in a fully TypeScript-based stack. In apps where the frontend and backend are tightly coupled and written in the same language, the "API contract" starts to feel more like overhead than architecture.

tRPC takes a different route. It skips the schema and instead relies on TypeScript's type inference to bridge the client-server gap. That means no manual type definitions, no GraphQL SDL, and no OpenAPI spec unless you explicitly need it. For internal tools, admin panels, or products built by small teams moving fast, this is often a worthwhile trade.

That said, tRPC isn't a silver bullet. If you're building a public API, need strong tooling support across multiple languages, or have complex API lifecycle requirements, REST and GraphQL are still better-suited. The goal isn't to abandon those tools, but to recognize when they're more complex than necessary for the problem at hand.

Final Thoughts

tRPC doesn't reinvent APIs, it rethinks how we build them when the frontend and backend are both in TypeScript. By removing the need for separate contracts, schemas, or generated types, it reduces friction without compromising on safety. You're still writing queries and mutations, but they feel more like calling functions than building API endpoints.

This shift works especially well in full-stack projects where speed, safety, and developer experience matter more than long-term API portability. It's not trying to replace REST or GraphQL in every case, but for a growing number of teams working in a shared TypeScript environment, it offers a more streamlined and intuitive alternative.

The next step is understanding what this new API layer makes possible. Whether it's cleaner validation, reusable auth middleware, or a more scalable router structure, tRPC opens up patterns that deserve a closer look.

This article was originally published on the GeekyAnts blog.

How to Mock in Integration Tests: Tools and Implementation

GeekyAnts Inc — Tue, 16 Jun 2026 07:36:11 +0000

This article was originally published on the GeekyAnts Blog. Author: Nilesh Kumar, Software Engineer II at GeekyAnts.

Having established when and why to mock in integration tests, it's time to explore the practical implementation of mocking strategies. This comprehensive guide covers the essential tools, techniques, and step-by-step processes for implementing effective mocks in your integration tests. We'll dive deep into popular mocking libraries, provide detailed examples, and explore advanced techniques for maintaining reliable and accurate mocks.

Essential Mocking Tools and Libraries

The JavaScript ecosystem offers several powerful tools for implementing mocks in integration tests. Each tool serves different purposes and excels in specific scenarios. Understanding their strengths and use cases will help you choose the right tool for your specific testing needs.

Nock: HTTP Request Mocking

Nock is the most popular and powerful HTTP request mocking library for Node.js. It allows you to intercept and mock HTTP requests at the network level, making it ideal for testing applications that interact with external APIs.

Key Features:

Intercepts HTTP requests at the network level
Supports complex request matching patterns
Provides detailed request/response validation
Offers recording and playback capabilities
Integrates seamlessly with all testing frameworks
Supports both REST and GraphQL APIs

When to Use Nock:

Testing interactions with external REST APIs
Mocking third-party services like payment gateways
Testing error handling for HTTP failures
Validating request formats and headers
Creating deterministic responses for external services

Basic Nock Usage:

const nock = require('nock');

// Mock a GET request
nock('https://api.example.com')
  .get('/users/1')
  .reply(200, {
    id: 1,
    name: 'John Doe',
    email: 'john@example.com'
  });

// Mock a POST request with request body matching
nock('https://api.example.com')
  .post('/users', { name: 'Jane Doe', email: 'jane@example.com' })
  .reply(201, { id: 2, name: 'Jane Doe' });

// Mock with headers
nock('https://api.example.com')
  .get('/protected-resource')
  .matchHeader('Authorization', 'Bearer my-token')
  .reply(200, { data: 'secret' });

// Mock an error response
nock('https://api.example.com')
  .get('/flaky-endpoint')
  .replyWithError('Connection refused');

// Clean up after tests
afterEach(() => {
  nock.cleanAll();
});

Sinon: Comprehensive Function Mocking

Sinon is a versatile library that provides spies, stubs, and mocks for JavaScript functions and objects. It's particularly useful for mocking internal dependencies and complex object interactions.

Key Features:

Function spies for monitoring calls
Stubs for replacing function behavior
Mocks for complex object interactions
Fake timers for time-based testing
Extensive assertion capabilities
Works with any testing framework

When to Use Sinon:

Mocking internal service dependencies
Testing time-based functionality
Spying on function calls and arguments
Stubbing complex object methods
Testing callback and promise behavior

Basic Sinon Usage:

const sinon = require('sinon');

describe('UserService', () => {
  let sandbox;

  beforeEach(() => {
    sandbox = sinon.createSandbox();
  });

  afterEach(() => {
    sandbox.restore();
  });

  it('should call the email service on registration', async () => {
    // Create a spy
    const emailSpy = sandbox.spy(emailService, 'sendWelcomeEmail');

    await userService.register({ name: 'Alice', email: 'alice@example.com' });

    sinon.assert.calledOnce(emailSpy);
    sinon.assert.calledWith(emailSpy, 'alice@example.com');
  });

  it('should handle email service failure gracefully', async () => {
    // Stub to simulate failure
    sandbox.stub(emailService, 'sendWelcomeEmail').rejects(new Error('SMTP error'));

    const result = await userService.register({ name: 'Bob', email: 'bob@example.com' });

    expect(result.status).toBe('registered_without_email');
  });

  it('should expire tokens after timeout', async () => {
    const clock = sandbox.useFakeTimers();

    const token = await authService.createToken('user-123');
    clock.tick(3600 * 1000); // Advance 1 hour

    const isValid = await authService.validateToken(token);
    expect(isValid).toBe(false);

    clock.restore();
  });
});

Jest Built-in Mocking

Jest provides powerful built-in mocking capabilities that integrate seamlessly with the testing framework. While not as specialized as Nock or Sinon, Jest mocking is convenient for simple scenarios and module-level mocking.

Key Features:

Module mocking with automatic mock generation
Function mocking with call tracking
Timer mocking for time-based tests
Snapshot testing for mocked responses
Mock clearing and restoration utilities

When to Use Jest Mocking:

Simple function mocking scenarios
Module-level mocking
Quick prototyping of mocks
Integration with Jest snapshot testing

Basic Jest Mocking:

// Auto-mock an entire module
jest.mock('./emailService');

// Manual mock with implementation
jest.mock('./paymentGateway', () => ({
  charge: jest.fn().mockResolvedValue({ success: true, transactionId: 'txn_123' }),
  refund: jest.fn().mockResolvedValue({ success: true }),
}));

describe('OrderService', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('should process payment on order placement', async () => {
    const { charge } = require('./paymentGateway');

    await orderService.placeOrder({ userId: 1, items: [...], total: 99.99 });

    expect(charge).toHaveBeenCalledWith({
      amount: 99.99,
      currency: 'USD',
      userId: 1,
    });
  });

  it('should handle payment failure', async () => {
    const { charge } = require('./paymentGateway');
    charge.mockRejectedValueOnce(new Error('Card declined'));

    await expect(
      orderService.placeOrder({ userId: 1, items: [...], total: 99.99 })
    ).rejects.toThrow('Payment failed');
  });
});

Step-by-Step Implementation Guide

Let's walk through a comprehensive example implementing integration tests with strategic mocking for a user notification system.

Application Architecture

Our example notification system includes:

NotificationService — orchestrates sending notifications
EmailProvider — external SMTP/email API
SMSProvider — external SMS gateway
UserRepository — database layer for user data
NotificationLog — records sent notifications

Step 1: Test Environment Setup

// test/setup.js
const nock = require('nock');
const { MongoMemoryServer } = require('mongodb-memory-server');

let mongoServer;

beforeAll(async () => {
  // Spin up in-memory MongoDB
  mongoServer = await MongoMemoryServer.create();
  process.env.MONGO_URI = mongoServer.getUri();

  // Disable real HTTP calls during tests
  nock.disableNetConnect();
  nock.enableNetConnect('127.0.0.1'); // allow localhost
});

afterAll(async () => {
  await mongoServer.stop();
  nock.enableNetConnect();
});

afterEach(() => {
  nock.cleanAll();
});

Step 2: Basic Integration Test with Mocking

// test/notification.integration.test.js
const request = require('supertest');
const nock = require('nock');
const app = require('../src/app');
const { seedUser } = require('./helpers/seed');

describe('POST /notifications/send', () => {
  let user;

  beforeEach(async () => {
    user = await seedUser({ email: 'user@example.com', phone: '+1234567890' });
  });

  it('should send email and SMS notifications successfully', async () => {
    // Mock email provider
    nock('https://api.sendgrid.com')
      .post('/v3/mail/send')
      .reply(202, { message: 'Accepted' });

    // Mock SMS provider
    nock('https://api.twilio.com')
      .post(`/2010-04-01/Accounts/${process.env.TWILIO_SID}/Messages.json`)
      .reply(201, { sid: 'SM123', status: 'queued' });

    const response = await request(app)
      .post('/notifications/send')
      .send({ userId: user.id, message: 'Your order has shipped!' })
      .set('Authorization', `Bearer ${process.env.TEST_API_KEY}`);

    expect(response.status).toBe(200);
    expect(response.body).toMatchObject({
      email: { status: 'sent' },
      sms: { status: 'queued' },
    });
  });

  it('should still send SMS if email provider fails', async () => {
    nock('https://api.sendgrid.com')
      .post('/v3/mail/send')
      .reply(500, { error: 'Internal Server Error' });

    nock('https://api.twilio.com')
      .post(`/2010-04-01/Accounts/${process.env.TWILIO_SID}/Messages.json`)
      .reply(201, { sid: 'SM456', status: 'queued' });

    const response = await request(app)
      .post('/notifications/send')
      .send({ userId: user.id, message: 'Your order has shipped!' })
      .set('Authorization', `Bearer ${process.env.TEST_API_KEY}`);

    expect(response.status).toBe(207); // Partial success
    expect(response.body.email.status).toBe('failed');
    expect(response.body.sms.status).toBe('queued');
  });
});

Step 3: Advanced Mocking Scenarios

Dynamic Response Generation:

// Respond differently based on request body
nock('https://api.sendgrid.com')
  .post('/v3/mail/send', (body) => body.to === 'vip@example.com')
  .reply(202, { priority: 'high' });

nock('https://api.sendgrid.com')
  .post('/v3/mail/send')
  .reply(202, { priority: 'normal' });

Simulating Rate Limits:

// First 3 calls succeed, then rate limit kicks in
nock('https://api.sendgrid.com')
  .post('/v3/mail/send')
  .times(3)
  .reply(202)
  .post('/v3/mail/send')
  .reply(429, { error: 'Too Many Requests' });

Conditional Mocking Based on Environment:

const mockExternalServices = () => {
  if (process.env.NODE_ENV === 'test') {
    nock('https://api.sendgrid.com')
      .persist()
      .post('/v3/mail/send')
      .reply(202);

    nock('https://api.twilio.com')
      .persist()
      .post(/Messages\.json$/)
      .reply(201, { status: 'queued' });
  }
};

Step 4: Performance Testing with Mocks

it('should handle 100 concurrent notification requests', async () => {
  nock('https://api.sendgrid.com')
    .post('/v3/mail/send')
    .times(100)
    .reply(202);

  nock('https://api.twilio.com')
    .post(/Messages\.json$/)
    .times(100)
    .reply(201, { status: 'queued' });

  const requests = Array.from({ length: 100 }, (_, i) =>
    request(app)
      .post('/notifications/send')
      .send({ userId: `user-${i}`, message: 'Test notification' })
      .set('Authorization', `Bearer ${process.env.TEST_API_KEY}`)
  );

  const start = Date.now();
  const responses = await Promise.all(requests);
  const duration = Date.now() - start;

  expect(responses.every((r) => r.status === 200)).toBe(true);
  expect(duration).toBeLessThan(5000); // Should complete in under 5 seconds
});

Advanced Mocking Techniques

Request Recording and Playback

Use Nock's record mode to capture real API responses and replay them in tests — great for staying in sync with real API behaviour without hitting production systems on every run.

// Record mode (run once against real APIs)
if (process.env.RECORD_MOCKS === 'true') {
  nock.recorder.rec({ output_objects: true });
}

// Playback mode (default)
const recordings = require('./fixtures/api-recordings.json');
nock.define(recordings);

Mock Validation and Maintenance

Always assert that all registered mocks were actually called — this catches dead code and stale mocks early:

afterEach(() => {
  // Verify all registered nock interceptors were used
  expect(nock.pendingMocks()).toHaveLength(0);
  nock.cleanAll();
});

Best Practices for Mock Implementation

1. Keep Mocks Simple and Focused
Each mock should represent exactly one scenario. Avoid overloading a single mock with conditional logic — create separate test cases instead.

2. Use Realistic Data and Delays
Make your mocks representative of real system behaviour. Add response delays where appropriate and use production-like payloads:

nock('https://api.sendgrid.com')
  .post('/v3/mail/send')
  .delay(120) // Simulate realistic network latency
  .reply(202, { message: 'Accepted' });

3. Mock at the Appropriate Level

Use Nock for external HTTP services
Use Sinon stubs for internal module dependencies
Use in-memory databases rather than mocking the DB layer

4. Document Mock Decisions
Leave comments explaining why a mock was introduced, what real behaviour it replaces, and when it should be revisited:

// Mocking SendGrid because the free tier has strict rate limits
// in CI. Review if we upgrade to a paid plan — real integration
// tests would be preferable.
nock('https://api.sendgrid.com')
  .post('/v3/mail/send')
  .reply(202);

Conclusion

Implementing effective mocks in integration tests requires careful consideration of tools, techniques, and maintenance strategies. The key is to use mocks strategically to eliminate problematic external dependencies while preserving the authentic integrations that provide the most value.

Nock excels at HTTP request mocking and is essential for testing external API integrations.
Sinon provides comprehensive function and object mocking capabilities for internal dependencies.
Jest's built-in mocking works well for simple scenarios and integrates seamlessly with the testing framework.

By following the patterns and best practices in this guide, you can create integration tests that give you genuine confidence in your system's behaviour while remaining practical to execute and maintain.

Remember: mocks are tools to enable effective testing, not goals in themselves. Always evaluate whether your mocking strategy is serving your testing objectives — and adjust as your application evolves.

Originally published on GeekyAnts Blog by Nilesh Kumar.

Katalon and the Rise of Low-Code Test Automation

GeekyAnts Inc — Thu, 11 Jun 2026 09:54:05 +0000

This article was originally published on the GeekyAnts Blog by Sankalp Nihal Pandey, Software Engineer at GeekyAnts.

Modern software development is faster than ever, with Agile and DevOps practices pushing teams to deliver features in weeks, sometimes even days. While this speed boosts innovation, it also creates a major challenge: ensuring quality in every release. Traditional automation frameworks such as Selenium and Appium are powerful but require deep programming knowledge and significant time to implement. Many QA teams end up spending more time writing and maintaining scripts than actually running tests.

This is where low-code test automation tools like Katalon Studio make a difference. Katalon empowers both technical and non-technical testers to create, manage, and execute automated tests quickly. In this blog, we'll explore Katalon in detail, examine its functionality through code snippets, and discuss its benefits for both testers and businesses.

What is Low-Code Test Automation?

Low-code test automation is an approach that minimizes the need for writing complex scripts. Instead, it offers a combination of:

Visual interfaces
Record-and-playback capabilities
Keyword-driven testing
Drag-and-drop components

This doesn't mean advanced users are left out. Tools like Katalon let engineers extend and customize tests using Groovy, a language based on Java. The result is a platform where manual testers, business analysts, and developers can all contribute — making automation more collaborative and scalable.

Why Katalon Studio?

Katalon Studio stands out as a multi-purpose automation platform built on top of Selenium and Appium. It supports:

Web application testing
Mobile app testing (Android & iOS)
API testing (REST & SOAP)
Desktop application testing

Its dual approach — a Manual View for non-technical users and a Script View for coders — makes it suitable for diverse teams. With built-in features like self-healing tests, data-driven testing, and CI/CD integration, Katalon reduces the effort needed to build robust automation frameworks from scratch.

Getting Started with Katalon: A Simple Example

Imagine testing a basic login functionality. In Katalon's Manual View, you can record user actions like opening a browser, typing a username and password, and clicking the login button. These actions are automatically converted into test steps:

WebUI.openBrowser('')
WebUI.navigateToUrl('https://example.com/login')
WebUI.setText(findTestObject('Page_Login/input_Username'), 'testuser')
WebUI.setEncryptedText(findTestObject('Page_Login/input_Password'), 'encrypted_password')
WebUI.click(findTestObject('Page_Login/button_Login'))
WebUI.verifyElementPresent(findTestObject('Page_Home/icon_UserProfile'), 10)
WebUI.closeBrowser()

Clean, readable, and generated without writing a single line manually — this is low-code in action.

Scaling Up: Data-Driven Testing

Real-world applications require testing with different sets of data. Katalon simplifies this with its data-driven testing feature, which allows linking test cases with external data sources like Excel, CSV, or databases — enabling you to run the same test across multiple user scenarios without duplicating scripts.

API Testing Made Easy

Katalon is not limited to UI automation. It also supports API testing, which is essential in microservices and cloud-native architectures. With just a few steps, you can send requests and validate responses:

ResponseObject response = WS.sendRequest(findTestObject('API/GetUser'))

WS.verifyResponseStatusCode(response, 200)
WS.verifyElementPropertyValue(response, 'data.id', '123')
WS.verifyElementPropertyValue(response, 'data.name', 'John Doe')

This makes end-to-end validation — from UI to backend — possible within a single platform.

Reducing Maintenance with Object Repository

A common pain in test automation is maintaining scripts when the UI changes. Katalon tackles this with its Object Repository, where locators and properties are stored separately from scripts. If a button ID changes, you update it once in the repository and all linked test cases are fixed instantly.

Additionally, Katalon offers self-healing tests, where AI automatically detects and substitutes broken locators — drastically reducing flaky tests and saving valuable engineering time.

CI/CD Integration for Agile Teams

Automation isn't useful if it's not integrated into the delivery pipeline. Katalon makes this seamless with plugins for Jenkins, GitLab, and Azure DevOps. Tests can be executed automatically with each build, providing instant feedback to developers.

Reporting and Analytics

Katalon provides comprehensive reporting out of the box. Test results include execution logs, pass/fail summaries, and screenshots for failed cases. For teams seeking deeper insights, Katalon TestOps offers advanced dashboards and analytics — helping organizations make data-driven decisions about quality.

When and Why to Use Katalon

Katalon fits particularly well in these scenarios:

Use Case	Description
Regression Testing	Automating repetitive checks across builds
Smoke Testing	Quickly validating core functionality
Cross-Browser Testing	Chrome, Firefox, Edge, Safari
Mobile Testing	Android and iOS applications
UAT	Business stakeholders validate workflows with minimal coding

From a business perspective, the advantages are clear: faster time-to-market, lower automation costs, and improved collaboration between QA, development, and product teams.

Limitations to Keep in Mind

No tool is perfect. While Katalon offers broad features, it does have some limitations:

Advanced customizations still require scripting knowledge
The free edition has limitations compared to the enterprise version
For highly complex backend systems, custom frameworks may still be a better fit

Conclusion

Low-code automation is no longer just a trend — it's a necessity for organizations that want to deliver faster without sacrificing quality. Katalon Studio is leading this revolution by providing an all-in-one platform that balances ease of use with advanced flexibility.

By combining record-and-playback simplicity with powerful scripting, data-driven testing, CI/CD integration, and AI-powered self-healing, Katalon empowers teams to test smarter, collaborate better, and release faster.

Whether you are a manual tester stepping into automation or a senior QA engineer building scalable solutions, Katalon offers a pathway that grows with your team.

Originally published at GeekyAnts Blog. Written by Sankalp Nihal Pandey, Software Engineer at GeekyAnts.