DEV Community: L Anil Kumar Singha

What Happens When an MCP Tool Call Never Returns?

L Anil Kumar Singha — Thu, 27 Aug 2026 04:57:27 +0000

A normal MCP tool call is straightforward: the client sends a request, the server runs the tool, and a response comes back.

A hang is different. The server accepts the call but never returns a result or an error.

I wanted to test how an MCP client behaves in that case without relying on network tricks or manually killing a process.

Reproducing a hang

MCP Failure Lab has a hang tool specifically for this.

The behavior is intentionally simple: once called, it doesn't resolve.

That gives us a repeatable failure instead of trying to approximate one with a very long delay.

A scenario for it looks like this:

{
  "name": "hung tool call times out",
  "call": {
    "tool": "hang",
    "args": {}
  },
  "timeoutMs": 1000,
  "expect": {
    "outcome": "timeout"
  }
}

The server behavior and the expected client behavior are separate here.

The server hangs.

The client is expected to time out after one second.

That distinction matters because a hung server doesn't produce a timeout by itself. The timeout has to be enforced by the client or by something around the request.

Hang vs delay

I originally treated a long delay as being close enough to a hang, but they're useful for testing different things.

A delayed call still has a completion point:

request ---- 5 seconds ----> response

A hung call doesn't:

request -------------------->
        -------------------->
        -------------------->

With a delay, a response can still arrive after the client has timed out.

With a hang, there is no eventual response.

That difference starts to matter when testing cancellation and cleanup.

A timeout only tells you what the client saw

Suppose a client calls a tool and gets a timeout.

It's tempting to treat that as meaning the operation failed.

That's not necessarily true.

Consider a tool that changes some state:

client                    server
   |                         |
   | ---- request ---------->|
   |                         | changes state
   |                         |
   |       response lost     X
   |
   | ---- timeout

The client saw a timeout, but the server may have already completed the operation.

If the client automatically retries, the operation might run twice.

This is one reason I'm interested in keeping the observed outcome separate from server state in Failure Lab.

It's also where simple timeout testing stops being enough.

What should happen after the timeout?

There are a few things worth checking beyond whether a timeout was thrown:

Is the original operation cancelled?
Is the MCP session still usable?
Can another tool call succeed?
Does the client retry?
Can you determine whether the original operation changed state?

The last one is particularly useful for tools with side effects.

Failure Lab supports an independent observe call for scenarios where state needs to be checked after the main call.

That lets a test distinguish between:

client observed: timeout
server state: unchanged

and:

client observed: timeout
server state: changed

Those are very different outcomes even though the client reported the same error.

Keeping the failure deterministic

The main reason I built the hang fault wasn't to simulate an unreliable network.

It was to remove the unreliable part from the test.

If the server hangs deterministically, I can run different clients against the same behavior and compare what they do.

The path still goes through MCP:

scenario
   ↓
MCP client
   ↓
transport
   ↓
MCP server
   ↓
hang

Only the failure is controlled.

That makes bugs around timeout handling much easier to reproduce.

Try it

The project is open source:

npx mcp-failure-lab demo

GitHub: https://github.com/anilloutombam/mcp-failure-lab

I'm working through other failure cases as well, particularly cancellation, session loss, malformed responses, and cases where the client reports failure even though the server changed state.

If you've hit an MCP failure that was difficult to reproduce, open an issue. I'd rather turn real failure cases into deterministic scenarios than invent them.

Introducing MCP Failure Lab: Testing MCP Beyond the Happy Path

L Anil Kumar Singha — Sat, 15 Aug 2026 19:21:09 +0000

Most MCP examples focus on successful tool calls. That is useful for getting started, but production systems also need to handle calls that stall, exceed their timeout, get cancelled, or lose their connection.

I started building MCP Failure Lab to make those failure paths controlled, repeatable, and easier to test.

What is MCP Failure Lab?

MCP Failure Lab is an open-source TypeScript toolkit for testing how MCP clients and related systems respond to failure conditions.

The project currently includes:

Deterministic delay, hang, and disconnect fault tools
A TypeScript CLI and stdio MCP server
A code-first scenario runner
Success, error, timeout, and duration assertions
Unit and integration tests
CI, coverage, dependency, and security checks

Instead of relying on unreliable network conditions or arbitrary sleeps, the goal is to provide explicit failure behavior that can be reproduced in a test suite.

Why build this?

A successful tool call only proves the happy path.

It does not tell us whether a client:

Enforces request timeouts
Cancels work correctly
Cleans up resources after failure
Distinguishes tool errors from transport failures
Recovers after a connection is interrupted
Produces useful diagnostic information

These behaviors become increasingly important as MCP integrations move beyond local experiments.

Current architecture

Fault tools are registered directly on an MCP server. Tests connect through MCP transports and exercise the same protocol path used by real tool calls.

The scenario runner adds a small testing layer around those calls. A scenario describes:

Which tool to call
Which arguments to provide
The request timeout
The expected outcome
Optional duration limits

The runner records the observed result and evaluates the configured assertions.

This keeps the project code-first, type-safe, and suitable for existing TypeScript test suites.

What comes next?

The project is still early, and there are several areas where contributions would be valuable:

Each issue includes its expected behavior, acceptance criteria, limitations, and relevant files.

Before starting substantial work, please comment on the issue with your proposed approach and ask to be assigned. This helps avoid duplicated work and gives us a place to discuss the design first.

Contributions are welcome

If you work with MCP, TypeScript, resilience testing, or developer tooling, I would value your feedback.

You can contribute code, review the design, improve documentation, test the project, or suggest failure modes that are worth supporting.

MCP Failure Lab is available on GitHub:

https://github.com/anilloutombam/mcp-failure-lab

If the project is useful to you, consider starring it, opening a discussion, or picking up one of the contributor-ready issues. I would be glad to build it with others.

How I Designed a Production Global Search System on PostgreSQL

L Anil Kumar Singha — Fri, 14 Aug 2026 16:41:28 +0000

Search often starts as a text box.

Then the requirements arrive.

Users want to search by a specific field. Then multiple fields. Then exclusions. Date ranges. Multi-select filters. AND, OR, NOT. Parentheses. Nested conditions.

Eventually, this:

payment approval

turns into this:

(
  "payment approval"
  OR (
    department:finance
    AND (status:open OR status:pending)
  )
)
AND NOT (
  owner:system
  OR category:archived
)

At that point, you're no longer building a text box.

You're designing a query language.

I ran into exactly this while designing a global search system for a production application.

From the user's perspective, I wanted the experience to remain simple: one global search surface, similar to the issue-search experience developers are familiar with in tools like GitHub or GitLab.

Underneath, the requirements evolved into a Lucene-style query model supporting:

free-text search
key:value filters
quoted phrases
AND, OR, and NOT
parentheses and grouping
recursively nested expressions
text filters
date ranges
multi-select fields
column-level filtering

But there was one requirement I considered just as important as the query language itself:

Users shouldn't need to understand the query language to use it.

So the system supported two ways of expressing the same search intent.

Power users could write the query directly.

Everyone else could build it through column-level filters. Depending on the field, the UI provided a text input, date-range picker, multi-select dropdown, or Boolean condition and constructed the expression as the user filtered.

Then the production dataset grew, and a second problem emerged:

free-text search performance.

That eventually led to another architectural decision:

Do I introduce a dedicated search engine, or can PostgreSQL continue owning search?

I kept PostgreSQL.

After profiling the expensive path and moving the free-text workload to a GIN-backed indexing strategy, measured search latency dropped from roughly 40ms to 12ms on a production dataset containing more than 20,000 records at the time.

The performance number is useful, but it isn't the most interesting part of the story.

What interested me more was how one search box ended up touching UX design, language parsing, recursive data structures, database performance, and infrastructure trade-offs.

One search box, different levels of precision

I didn't want advanced search to make basic search harder.

Someone should always be able to type:

payment approval

and search normally.

Nothing else should be required.

A user who knows exactly what they're looking for can be more specific:

status:open

or:

owner:"John Doe"

Free text and structured conditions can be combined:

"payment approval" AND status:open

And power users can go much further:

("payment approval" OR refund)
AND (status:open OR status:pending)
AND NOT owner:system

This gave the search experience progressive complexity.

You don't need to understand the language to start searching.

But when you need more precision, the language is there.

The next problem was usability.

Most users shouldn't have to learn that syntax.

So I didn't make them.

The UI could write the query for you

Alongside the global search input, I designed column-level filtering.

The control shown to the user depended on the type of data being filtered.

For text:

Owner
┌────────────────────────┐
│ John                   │
└────────────────────────┘

For dates:

Created Date

From: 01 Aug 2026
To:   14 Aug 2026

For predefined values:

Status

✓ Open
✓ Pending

Conditions could also include or exclude values:

Status
AND
Open

or:

Status
NOT
Archived

As users interacted with those controls, the application constructed the corresponding search expression.

A user might interact with something like:

Search: payment approval

Status:
  ✓ Open
  ✓ Pending

Owner:
  NOT System

Created:
  Aug 1 → Aug 14

while the system represented the same intent as something equivalent to:

"payment approval"
AND (status:open OR status:pending)
AND NOT owner:system
AND createdDate:[2026-08-01 TO 2026-08-14]

The user didn't need to write that.

The UI did it for them.

That became an important principle in the design:

A system can support a sophisticated query language without requiring users to speak that language.

Two interfaces, one search model

I didn't want the visual filter builder and the advanced query input to become two independent search implementations.

That would eventually create two sets of semantics, two places for bugs, and two implementations that could disagree about what the same filter means.

Instead, both interfaces converged on the same search model.

        ┌─────────────────────────┐
        │    Global Search Box    │
        │                         │
        │ Lucene-style syntax     │
        └────────────┬────────────┘
                     │
                     ▼
              Search Expression
                     ▲
                     │
        ┌────────────┴────────────┐
        │ Column Filter Builder   │
        │                         │
        │ • Text input            │
        │ • Date range            │
        │ • Multi-select          │
        │ • AND / NOT             │
        └─────────────────────────┘

From there, the expression entered the same processing pipeline:

Search Expression
       │
       ▼
   Tokenizer
       │
       ▼
     Parser
       │
       ▼
      AST
       │
       ▼
   Validation
       │
       ▼
 Query Compiler
       │
       ▼
 Prisma / SQL
       │
       ▼
  PostgreSQL

There weren't two search engines.

There were two ways of expressing the same search intent.

That distinction kept the architecture much easier to reason about.

When search became a language

Boolean operators changed the nature of the problem.

Consider:

status:open OR status:pending AND priority:high

With normal Boolean precedence, that means:

status:open
OR
(status:pending AND priority:high)

which is different from:

(status:open OR status:pending)
AND priority:high

Now add NOT:

(status:open OR status:pending)
AND NOT owner:system

Then nested grouping:

(
  status:open
  OR (
    status:pending
    AND (
      priority:high
      OR priority:critical
    )
  )
)
AND NOT owner:system

At this point, .split("AND") isn't an architecture.

Neither is continuing to grow a regular expression until nobody wants to touch it.

The requirement had crossed an architectural boundary.

I needed a parser.

Treating search like a small compiler

I ended up treating the search input similarly to a small language-processing pipeline:

Raw Query
    │
    ▼
Tokenizer
    │
    ▼
 Parser
    │
    ▼
   AST
    │
    ▼
Validator
    │
    ▼
Compiler
    │
    ▼
PostgreSQL

Each stage had a narrow responsibility.

The tokenizer identified meaningful pieces of the language.

The parser determined how those pieces related to each other.

The AST represented the user's intent independently of the original string.

The validator ensured that only supported fields and operations could be used.

The compiler translated that structured representation into database conditions.

That separation mattered.

The parser didn't need to understand how PostgreSQL executed search.

PostgreSQL didn't need to understand our user-facing syntax.

And the database layer didn't need to repeatedly reinterpret an arbitrary search string.

From a query string to structured data

Take:

(payment OR refund) AND status:open

The tokenizer can identify units such as:

LPAREN
TEXT(payment)
OR
TEXT(refund)
RPAREN
AND
FIELD(status, open)

Quoted values remain intact:

owner:"John Doe"

as do quoted free-text phrases:

"payment approval"

Parentheses and Boolean operators remain explicit because they determine the structure of the expression.

Now consider:

(payment OR refund) AND NOT status:archived

Instead of carrying that string through the application, the parser can represent its meaning as a tree:

                 AND
                /   \
              OR     NOT
             /  \      \
      payment  refund   FIELD
                         │
                   status:archived

A simplified TypeScript representation could look like:

type SearchNode =
  | {
      type: "text";
      value: string;
    }
  | {
      type: "field";
      field: string;
      value: string;
    }
  | {
      type: "and" | "or";
      left: SearchNode;
      right: SearchNode;
    }
  | {
      type: "not";
      operand: SearchNode;
    };

The exact TypeScript isn't the interesting part.

The boundary is.

The user's arbitrary string has become structured data that can be validated, transformed, tested, and compiled.

Supporting N-level nested search

I didn't want the grammar to contain a hard-coded concept of:

level 1
level 2
level 3

Expressions are recursive.

Conceptually:

Expression :=
    FreeText
  | FieldCondition
  | NOT Expression
  | (Expression)
  | Expression AND Expression
  | Expression OR Expression

An expression can contain another expression, which can contain another expression.

So:

A AND (B OR (C AND (D OR (E AND NOT F))))

doesn't require special handling.

It's simply a deeper tree:

The compiler recursively walks the tree.

There is no fixed application-level nesting depth in the search grammar.

That lets users continue composing conditions when they need more precision instead of running into an arbitrary maximum number of filter groups.

Of course, that doesn't mean execution has infinite resources.

Request size, runtime behavior, query complexity, timeouts, and infrastructure still create practical boundaries.

Those are operational constraints rather than artificial limits in the grammar.

Search fields are an API, not database columns

Supporting:

status:open

raises another question.

What happens if someone tries:

someInternalDatabaseField:value

A search language shouldn't automatically become an interface to the underlying database schema.

Instead, searchable fields should be explicitly supported.

A simplified mapping might look like:

const searchableFields = {
  status: /* internal mapping */,
  owner: /* internal mapping */,
  category: /* internal mapping */,
  priority: /* internal mapping */,
};

The actual implementation can contain considerably more metadata because different fields require different controls, validation rules, and database behavior.

But the principle is simple:

The search language has its own contract.

A field becomes searchable because the application deliberately exposes it, not because a similarly named PostgreSQL column happens to exist.

That also gives the database schema room to evolve without necessarily breaking the query syntax users already know.

Then the dataset grew

The most complicated-looking part of this architecture wasn't where I encountered the main performance problem.

The parser worked.

Recursive expressions worked.

Structured filters worked.

The problem appeared somewhere much less exotic:

free-text search.

When the dataset was smaller, the existing implementation performed well enough.

Then production data accumulated.

The same kind of free-text search now had increasingly more data to work through.

The code hadn't necessarily regressed.

The workload had changed.

That's an important distinction.

A query that behaves perfectly well at one data volume can have very different characteristics as that volume grows.

So I didn't start by optimizing the parser.

I started by measuring the database path.

Measure before changing the architecture

I wanted to understand what PostgreSQL was actually doing.

EXPLAIN ANALYZE was part of that investigation.

EXPLAIN ANALYZE
SELECT ...

I was looking for answers to concrete questions:

How many rows are being examined?
Are we scanning more data than necessary?
Are the indexes I expect actually being used?
Which part of the generated condition is expensive?
Where is execution time being spent?
How does the execution plan behave as the dataset grows?

This distinction mattered.

The system contained sophisticated application code, but optimizing the most complicated-looking code wouldn't help if PostgreSQL was doing the expensive work.

Optimize what the measurements tell you is expensive, not what looks complicated.

Why GIN fit the workload

Structured filters and free text have different access patterns.

A B-tree index is a natural fit for many structured conditions:

WHERE status = 'OPEN'

Free-text search asks a different kind of question:

Which records contain these searchable terms?

That's where an inverted index becomes useful.

PostgreSQL already provides this capability through GIN — Generalized Inverted Index.

At a high level, an inverted index maintains relationships between searchable terms and the records containing them.

payment ─────► Record 12
        ├────► Record 48
        └────► Record 91

approval ────► Record 12
         └───► Record 103

invoice ─────► Record 27
        └────► Record 91

A simplified PostgreSQL example might look like:

CREATE INDEX idx_records_search
ON records
USING GIN (
  to_tsvector('english', searchable_text)
);

with a corresponding full-text condition:

SELECT id, title
FROM records
WHERE
  to_tsvector('english', searchable_text)
  @@ plainto_tsquery('english', 'payment approval');

The production implementation was more involved because free text could appear alongside structured conditions and recursively nested Boolean expressions.

Architecturally, though, the responsibilities remained separate:

                     Search AST
                         │
               ┌─────────┴─────────┐
               ▼                   ▼
         Structured            Free Text
          Conditions              Search
               │                   │
               ▼                   ▼
          Appropriate             GIN
           indexes               index
               │                   │
               └─────────┬─────────┘
                         ▼
                     PostgreSQL

The query language remained expressive while the expensive free-text path could be optimized independently.

From roughly 40ms to 12ms

After optimizing the free-text path around the appropriate PostgreSQL indexing strategy, measured search latency moved approximately from:

Before       After
 ~40ms   →    ~12ms

That's roughly a 70% reduction for the workload we measured.

The production dataset contained more than 20,000 records at the time.

That result needs context.

It does not mean:

Add GIN and PostgreSQL becomes 70% faster.

Database performance depends on schema, data distribution, query shape, hardware, cache state, and workload.

The useful part is the process:

Observe
   ↓
Measure
   ↓
Inspect the execution plan
   ↓
Understand the access pattern
   ↓
Choose the appropriate index
   ↓
Measure again

GIN fit our access pattern.

The decision came from the workload, not the other way around.

Why I didn't introduce Elasticsearch

Once free-text search became a performance discussion, a dedicated search engine was an obvious option to consider.

Elasticsearch could handle this kind of search.

But capability alone wasn't enough reason for me to introduce another system.

PostgreSQL was already part of the production architecture and remained the source of truth.

Keeping search there meant the architecture remained roughly:

              Application
                   │
                   ▼
              PostgreSQL
             ┌─────┴─────┐
             │           │
       Structured     Free Text
         Search         Search
             │           │
        Appropriate     GIN
         indexes        index

Introducing another search datastore changes that:

                   Application
                        │
                ┌───────┴───────┐
                ▼               ▼
           PostgreSQL      Search Engine
                │               ▲
                └───── Sync ────┘

That synchronization arrow looks small on an architecture diagram.

Operationally, it isn't.

It introduces concerns around:

data synchronization
eventual consistency
failed indexing operations
retry and replay
index rebuilding
mappings
monitoring
deployments and upgrades
infrastructure cost
another failure domain

None of those make Elasticsearch a bad choice.

They're simply part of the cost of owning another system.

For our workload, PostgreSQL was already there, GIN matched the free-text access pattern, and the resulting performance satisfied the requirements.

Adding another datastore would have increased the operational surface without solving a problem we still had.

So I didn't add one.

GIN was an architectural decision, not just an index

It's easy to summarize the change as:

I added a GIN index and made search faster.

That's technically part of what happened.

But the architectural decision was larger.

I effectively had three directions:

                  Growing Search Cost
                         │
            ┌────────────┼────────────┐
            ▼            ▼            ▼
         Leave it     Optimize     Introduce
          as-is       PostgreSQL   Search Engine
                          │
                          ▼
                         GIN

Doing nothing wasn't going to age well.

A dedicated search engine could solve the problem, but it would introduce another operational component.

Optimizing PostgreSQL gave me a middle path:

Use more of the capabilities of the system we already operate before introducing another one.

That kept PostgreSQL as the source of truth.

No search synchronization pipeline.

No additional datastore.

No additional operational dependency.

And it met the performance requirements.

The question wasn't which technology was more powerful.

The question was which architecture introduced the right amount of complexity for the problem we actually had.

When I would introduce a dedicated search engine

This isn't an argument that PostgreSQL should replace Elasticsearch.

I'd revisit the architecture if the requirements started demanding things such as:

sophisticated relevance ranking
advanced fuzzy matching and typo tolerance
complex language-specific analysis
significantly larger search workloads
independent scaling of search
complex search aggregations
search-specific availability requirements

At that point, specialized search infrastructure may provide enough value to justify its operational cost.

The useful question isn't:

PostgreSQL or Elasticsearch?

It's:

Have the requirements crossed the point where owning another system is justified?

For us, they hadn't.

Leaving room to evolve without building the future

There was another reason I was comfortable keeping PostgreSQL.

The query language wasn't directly coupled to it.

The boundary looked roughly like:

User Intent
     │
     ▼
Search Expression
     │
     ▼
    AST
     │
     ▼
Validation
     │
     ▼
PostgreSQL Compiler
     │
     ▼
PostgreSQL

PostgreSQL was the current execution strategy.

It wasn't the definition of the search language.

If the requirements eventually justify another backend, there's a natural architectural seam:

                       AST
                        │
                ┌───────┴───────┐
                ▼               ▼
          PostgreSQL        Dedicated
           Compiler       Search Compiler

I wouldn't implement that second compiler today.

That's an important distinction.

Designing a boundary is useful. Building hypothetical infrastructure isn't.

What I'd do differently today

If I were starting this feature again, I'd formalize the query language earlier.

Search requirements tend to grow incrementally.

payment

becomes:

status:open

then:

payment AND status:open

then:

payment AND (status:open OR status:pending)

and eventually:

(
  payment
  OR (
    refund
    AND (status:open OR status:pending)
  )
)
AND NOT owner:system

At some point, you've created a language without explicitly deciding to create one.

Once structured fields, Boolean operators, and grouping start appearing in the requirements, I'd define the boundaries early:

Grammar
   ↓
Tokenizer
   ↓
Parser
   ↓
AST
   ↓
Validation
   ↓
Compilation
   ↓
Execution

That makes everything that follows easier to reason about and test.

What I took away from building it

Looking back, what appeared to be one feature was really three different engineering problems.

Expressiveness

Free text gradually became a query language:

free text
key:value
AND / OR / NOT
parentheses
recursive expressions

That required treating search as structured input:

tokenize → parse → AST → validate → compile

Usability

The query language could be powerful without becoming a prerequisite for using search.

The column-level filter builder exposed controls appropriate to the underlying data—text inputs, date ranges, multi-selects, and Boolean conditions—and generated the same search representation underneath.

Two interfaces. One search model.

The complexity stayed in the system instead of being pushed onto every user.

Scale

The part that looked complicated wasn't the part that eventually became expensive.

As the dataset grew, free-text search became the bottleneck.

The response wasn't to rewrite the parser or immediately introduce another datastore.

It was to measure the query path, inspect what PostgreSQL was doing, and optimize the access pattern that was actually expensive.

For our workload, a GIN-backed strategy brought measured search latency from roughly 40ms to 12ms while allowing PostgreSQL to remain the source of truth.

Could a dedicated search engine become the right architecture later?

Absolutely.

But I didn't want to pay the synchronization, consistency, infrastructure, and operational costs of another system before the requirements justified them.

That's probably the main thing I took away from building this:

Good architecture isn't about eliminating complexity. It's about putting complexity in the right place—and only introducing it when the problem actually requires it.

Your Dog Has Thoughts. I Built an AI to Translate Them 🐶

L Anil Kumar Singha — Fri, 14 Aug 2026 12:03:00 +0000

This is a submission for the Weekend Challenge: Dog Days Edition.

What I Built

I built Dog Mind, a playful AI-powered web app that turns a dog photo into an entertaining interpretation of the dog’s mood, visible body language, personality signals, and imaginary inner monologue.

Upload a photo and Dog Mind generates:

A cautious breed or dog-type guess
A mood and confidence score
Happiness, energy, and mischief ratings
Observations based on visible body-language signals
A short personality summary
A funny, family-friendly imaginary thought
A matching voice personality

After the analysis, users can hear the dog’s imagined thought spoken aloud, ask up to three follow-up questions, and download or share the final result card.

No dog photo available? The Try a sample dog button opens a pre-generated experience without consuming an AI request.

Dog Mind is made for entertainment. It does not claim to read a dog’s mind or provide veterinary or behavioral advice.

Demo

🐶 Live app: dog-mind-eight.vercel.app

To try it:

Upload a JPG, PNG, or WebP photo of a dog.
Select Analyze my dog.
Review the dog’s mood, signals, and imaginary inner monologue.
Select Hear this dog’s voice.
Ask the dog up to three playful questions.
Share or download the result card.

You can also select Try a sample dog for an instant preview.

Code

The complete source code is available on GitHub:

🐙 github.com/anilloutombam/dog-mind

How I Built It

Dog Mind uses:

Next.js
React
TypeScript
Tailwind CSS
Google Gemini
ElevenLabs
Zod
pnpm
Vercel

Multimodal dog analysis with Google Gemini

When a user uploads a photo, the browser sends it to a server-side Next.js route as multipart form data.

Before contacting Gemini, the server checks:

The declared MIME type
The file size
The actual binary image signature

This prevents renamed or unsupported files from being accepted based only on their extensions.

Gemini first determines whether the primary subject is a dog. For a valid dog photo, it returns structured JSON containing:

breedGuess
breedConfidence
dogSize
voiceStyle
mood
confidence
signals
observations
thought
summary

The shared Zod schema validates the complete response before it reaches the interface. It also enforces the same character and number limits expected by downstream features.

The prompt asks Gemini to interpret only clearly visible signals, avoid medical claims, make cautious breed guesses, and keep the imaginary thought short and family-friendly.

Giving the dog a voice with ElevenLabs

Dog Mind sends the generated inner monologue to ElevenLabs only after the user selects Hear this dog’s voice.

Gemini recommends one of six controlled voice personalities:

Bright
Warm
Bold
Dramatic
Gentle
Gruff

Each personality maps to approved ElevenLabs stability, style, and speed settings.

The voice choice is inspired by the dog’s visible size, expression, and energy. It is a playful creative decision, not a scientific claim about breed behavior.

Generated audio is cached by text and voice personality. Replaying the same voice can reuse the existing audio, while New take deliberately requests a fresh performance.

The audio cache uses a fixed size and removes older entries so it cannot grow indefinitely.

Ask Your Dog

After the initial analysis, users can continue the imaginary conversation by asking the dog up to three questions.

The follow-up request sends only the established dog persona and the new question. It does not upload the image again.

Gemini also acts as a topic guard. It rejects:

Unrelated questions
Role-changing instructions
Prompt-injection attempts
Requests to reveal internal prompts

Dog health questions receive no diagnosis or treatment advice.

The three-question limit is enforced on the server instead of relying only on a disabled client button. Conversation records expire after 24 hours, expired entries are pruned, and the process-local store has a maximum size.

The client persists the successful question count and synchronizes it between browser tabs. When the limit is reached, the API returns a machine-readable terminal state so the interface hides the form instead of displaying a misleading retry button.

Caching repeated image analysis

Gemini API requests are valuable, especially while working within free-tier limits.

Dog Mind calculates a SHA-256 digest of each uploaded image and uses it as a cache key. If the same image is analyzed again during the browser session, the validated result can be reused without another Gemini request.

Cached values are validated when they are read and written. Invalid stored values are removed instead of being trusted.

Handling stale requests

A user can select another image, reset the experience, or open the sample result while an earlier request is still running.

To prevent an old response from replacing a newer state, Dog Mind:

Assigns a generation number to each analysis
Cancels superseded requests with AbortController
Checks the generation after asynchronous operations
Discards responses that no longer belong to the active image

This keeps the UI consistent even when users move quickly between states.

Friendly failure and quota handling

AI APIs can fail because of temporary capacity, rate limits, exhausted quotas, network problems, or invalid responses.

Dog Mind provides:

Friendly Gemini 429 messages
Retry timing from response metadata
Live retry countdowns
Disabled retry controls during cooldowns
Retry actions for analysis, voice generation, and dog chat
Provider timeouts
Safe request IDs for diagnostics
Graceful handling for non-dog images

The app also includes a pre-generated sample so visitors can still explore the main interface when the AI provider is temporarily unavailable.

Security and privacy

Security was an important part of the implementation:

Gemini and ElevenLabs credentials remain server-side
Images are checked in both the browser and server
Binary signatures are verified
Uploads are limited to 5 MB
AI responses are schema-validated
Client errors do not reveal credentials or stack traces
Follow-up prompts receive minimal dog context
API routes use request throttling and provider timeouts
Security headers prevent framing and MIME sniffing
Camera, microphone, and location access are disabled

Building the experience

I wanted Dog Mind to feel playful without becoming confusing.

The interface includes:

Drag-and-drop uploads
Full-image previews without cropping
Animated analysis progress
A running dog progress indicator
Rotating dog facts
Screen-reader announcements
Reduced-motion support
Responsive layouts
Native sharing where supported
Downloadable square result cards

The codebase uses a feature-first structure. Route files compose the page, feature modules own the workflow, and server utilities centralize validation, throttling, and safe error handling.

Interesting Challenges

Keeping playful AI output honest

Dog Mind creates a humorous interpretation of a dog’s expression, but the result should never be confused with a diagnosis or a factual reading of the animal’s thoughts.

The prompts, interface copy, and error messages consistently describe the output as an imaginary interpretation based on visible clues.

Coordinating multiple AI services

Gemini and ElevenLabs have different request formats, limits, errors, and response types.

Keeping both integrations behind server routes gave the browser one consistent application API while protecting provider credentials.

Designing useful recovery states

A failed request should not leave the user stuck.

Retry buttons, cooldown countdowns, cached results, audio reuse, stale-request cancellation, and the sample experience all help users continue without restarting the entire flow.

Prize Categories

Best Use of Google AI

Google Gemini powers the core multimodal experience. It examines dog photos, identifies visible body-language signals, produces structured mood data, creates the imaginary inner monologue, recommends a controlled voice personality, and handles guarded follow-up conversations.

Best Use of ElevenLabs

ElevenLabs transforms the dog’s imaginary thought and optional follow-up replies into expressive voice performances. Controlled presets adapt stability, speed, and expression to complement the visual analysis.

What I Learned

Dog Mind began with a funny question:

What if AI could translate the look your dog gives you?

Building it showed me that playful AI products still need careful engineering.

Schema validation, file-signature checks, caching, rate-limit handling, stale-request protection, prompt-injection resistance, accessibility, and honest disclaimers made the experience more reliable and enjoyable.

The best AI experience is not only about generating an answer. It is also about presenting that answer with the right personality, boundaries, and recovery path when something goes wrong.

Thanks for checking out Dog Mind! 🐾

Fixing an Infinite Loading State in the npmx Code Browser

L Anil Kumar Singha — Mon, 03 Aug 2026 08:23:15 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is an open-source package explorer for the npm ecosystem. It helps developers inspect package metadata, releases, dependencies, documentation, comparisons, and published source files.

Bug Fix or Performance Improvement

The npmx code browser has a fallback for files that exceed its supported display size. It should show a “File too large” warning and provide an option to open the raw file.

Instead, selecting an oversized file left the page displaying its loading state indefinitely.

The issue can be reproduced here:

https://npmx.dev/package-code/@types/vscode/v/1.118.0/index.d.ts

The corrected behaviour can be verified on the PR preview:

https://npmx-h3s403v0g-npmx.vercel.app/package-code/@types/vscode/v/1.118.0/index.d.ts

Code

GitHub issue: https://github.com/npmx-dev/npmx.dev/issues/2732

Pull request: https://github.com/npmx-dev/npmx.dev/pull/3120

The production fix is one line:

if (isFileTooLarge.value) return false

It was added to the page’s loading-state calculation:

const isLoading = computed<boolean>(() => {
  if (!isViewingFile.value) {
    return treeStatus.value !== 'success' && treeStatus.value !== 'error'
  }

  if (isFileTooLarge.value) return false

  return !fileStatus.value || fileStatus.value === 'pending' || fileStatus.value === 'idle'
})

My Improvements

The page already knew when a selected file exceeded the size limit. In that situation, it intentionally skipped the file-content request.

Because the request never started, its status remained idle. The loading logic treated that status as if the file were still waiting to load, so the loading skeleton prevented the existing fallback from appearing.

The new condition makes the page stop reporting a loading state when the file is already known to be too large. This allows the existing warning and raw-file action to render without changing the server limit or downloading unnecessary content.

I also added a regression test that verifies:

The large-file warning is displayed.
The page does not remain in its loading state.
The file-content endpoint is not called.
The raw-file action points to the correct jsDelivr URL.

The code change is small, but it fixes an important state-handling edge case: an idle request is not always waiting to begin. Sometimes the application has intentionally decided that it should not run.

If you're interested in more of my open-source work and engineering projects, you can explore my portfolio or follow my work on GitHub.

Fixing a Search Race Condition in npmx

L Anil Kumar Singha — Sat, 01 Aug 2026 07:55:07 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is a modern browser for the npm registry. It provides package search, version timelines, dependency information, comparisons, and other tools for exploring npm packages.

I've been contributing to npmx recently, mostly around search behavior and edge cases. One of those contributions started with a particularly interesting symptom:

The search failed the first time, but worked after a refresh.

Bug Fix or Performance Improvement

The bug was reported in issue #2617.

The reproduction was quite specific.

With instant search disabled and a saved page size of 50 or higher:

Open the search page.
Search for a package.
No package results appear.
The organization suggestion can still appear.
Refresh the exact same page.
The package results suddenly show up.

Same query. Same page size. Same application.

The refresh behavior was the interesting part.

If the packages didn't exist, refreshing shouldn't make them appear. And if the search request itself was fundamentally broken, I'd expect the second attempt to fail too.

That pointed away from the search data itself and toward what was happening during the initialization of the page.

Following the timing

npmx stores the user's preferred search page size locally.

On the first navigation to the search page, however, the initial search could begin before that saved preference had finished loading.

The sequence looked roughly like this:

Search page opens
        ↓
Initial search starts
(page size = 25)
        ↓
Saved preference loads
        ↓
Page size changes to 50
        ↓
fetchMore() runs
        ↓
Initial search is still pending

Individually, none of these operations were wrong.

The problem was when they happened relative to each other.

fetchMore() could run while the initial Algolia search was still pending.

At that moment, the search result hadn't arrived yet. fetchMore() could therefore read the temporary empty response and store that value in the search cache.

Then the original search completed with the real package results.

But it was too late.

The empty cached value could take priority, leaving the UI showing no packages even though the search had successfully returned them.

That also explained why refreshing appeared to magically fix the problem.

It wasn't magic.

The initialization timing had changed.

Code

The fix is in npmx-dev/npmx.dev#3109.

Instead of allowing fetchMore() to continue while the initial search is unresolved, it now checks whether that search is still pending and waits for it:

if (asyncData.status.value === 'pending') {
  await asyncData.refresh({ dedupe: 'defer' })
}

The important detail here is:

dedupe: 'defer'

I didn't want fetchMore() to cancel the search that was already running and replace it with another request.

It needed to join the existing in-flight request.

So the flow changed from something like:

Initial search ────────────────► package results
        │
        └── fetchMore()
                ↓
          reads empty state
                ↓
          empty value cached

to:

Initial search ────────────────► package results
                                      ↓
                               fetchMore() continues
                                      ↓
                               results preserved

It's a small change in code, but it changes the ordering guarantee between the two asynchronous operations.

My Improvements

The main fix was making fetchMore() wait for the pending initial search before consuming its result.

But a race-condition fix also needs a test that can reliably reproduce the timing that caused it.

Otherwise, the test might pass simply because the operations happened in a convenient order that particular time.

So I added a regression test that deliberately recreates the problematic sequence.

The test:

Starts the initial Algolia search.
Keeps that request pending.
Changes the requested page size.
Triggers the additional result-loading path.
Resolves the original search.
Verifies that the completed package results are preserved.

That was important because the test isn't relying on the race condition happening naturally.

It controls the timing.

After the fix, users with a saved page size of 50 or higher get their package results on the first search without needing to refresh the page.

What I took away from this bug

What made this issue interesting wasn't the amount of code required to fix it.

It was the symptom:

It doesn't work the first time, but refreshing fixes it.

That can be a useful debugging clue.

When persisted client state, initialization, caching, and asynchronous requests interact, a refresh can change the order in which those operations happen.

In this case, the individual pieces were working.

The initial search worked.

The saved preference worked.

fetchMore() worked.

The problem only appeared when they ran in a particular order.

The final fix wasn't to make the search faster or add another request.

It was simply to make one asynchronous operation respect another operation that was already in progress.

Sometimes fixing a race condition is less about doing more work and more about making sure the work you already have happens in the right order.

If you're interested in more of my open-source work and engineering projects, you can explore my portfolio or follow my work on GitHub.

Midnight Ramen: A Rainy CSS Art Love Letter to Comfort Food

L Anil Kumar Singha — Fri, 31 Jul 2026 15:29:29 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, CSS Art.

Inspiration

My inspiration was a warm bowl of ramen on a quiet, rainy night—the kind of meal that feels comforting before you even take the first bite.

I wanted to capture more than the food itself, so I created a complete midnight ramen-shop scene. The steaming bowl is surrounded by a glowing lantern, falling rain, a handwritten order slip, shelves of ingredients, and a tiny shop cat peeking over the counter.

Demo

You can also explore the source code on GitHub.

Journey

I created the illustration using HTML and CSS, without image assets or JavaScript. The bowl, broth, noodles, egg, chashu pork, nori, narutomaki, mushrooms, scallions, lantern, window, furniture, and cat are all composed from regular HTML elements.

The visual details rely on:

Layered CSS gradients
Borders and border radii
Pseudo-elements
Transforms and clipping
CSS custom properties
Responsive media queries
Subtle keyframe animations

The scene also includes CSS-only interactions. The chili-oil control changes the appearance of the broth and introduces small animated spice sparks. A compact day/night control changes the window, lantern, steam, and surrounding color palette without JavaScript.

The ingredient labels can be revealed with a mouse or keyboard. I also included prefers-reduced-motion support so visitors who disable animation receive a calmer version of the scene.

The most challenging part was creating depth while keeping the markup understandable. The ramen bowl contains several overlapping layers, and each topping needs to remain recognizable without using an image. Careful positioning, contrast, shadows, and restrained animation helped the individual pieces feel like one cohesive illustration.

I am particularly proud that the finished project requires only two files for the artwork: index.html and style.css. It can run directly in a browser without a framework, build process, or external JavaScript.

This project reminded me that CSS is not only a styling language—it can also be an expressive illustration medium.

Source

The complete source is available on GitHub.

The project is shared under the MIT License.

If you'd like to see more of what I'm building, you can explore my portfolio or find me on GitHub.

Fixing Exact Package Search Relevance in npmx

L Anil Kumar Singha — Fri, 31 Jul 2026 10:27:09 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is an open-source alternative interface for exploring packages from the npm registry. It provides package details, documentation, version history, dependencies, search tools, and other information for JavaScript developers.

Bug Fix or Performance Improvement

I worked on issue #2978, which was reported by another contributor.

When Algolia was selected as the search provider, the page displayed “Relevance” as the active sorting option. However, an exact package-name match did not always appear first.

For example, searching for napkin could show other packages above the exact match. Switching to “Downloads/wk” and then back to “Relevance” changed the results and moved napkin to the top.

I reproduced this behavior locally before investigating the cause.

Code

Issue #2978
Pull request: https://github.com/npmx-dev/npmx.dev/pull/3103

Before and after

Before

private-user-images.githubusercontent.com

After

private-user-images.githubusercontent.com

My Improvements

npmx already made an additional Algolia request to check whether a package with the exact searched name existed.

However, this request retrieved only the package name and used the result only as an existence check. If the exact package was missing from the initial batch of results, the application knew it existed but did not have enough information to display it.

I updated the exact-package request to retrieve the complete package information. When the returned package name matches the searched name, it is placed at the beginning of the results.

Before adding it, the code removes any existing occurrence of the same package. This prevents duplicate results.

I also added two safety checks during review:

A missing Algolia hits array falls back to an empty array.
A returned hit is promoted only when its name matches the requested package.

Finally, I added a regression test that supplies a regular search result and a separate exact-package result. The test verifies that the exact package is detected and placed first.

I validated the change by running the focused Nuxt tests, TypeScript checks, lint and formatting checks, and by testing the behavior manually in the local UI.

After the fix, an exact package-name match appears at the top immediately when “Relevance” is selected.

Fixing a False “TypeScript Types Removed” Event in npmx

L Anil Kumar Singha — Fri, 31 Jul 2026 08:43:14 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is an open-source browser for the npm registry. It helps developers explore package metadata, versions, dependencies, documentation, and other information.

I worked on npmx issue #2791, which reported an incorrect event in the package-version timeline. npmx could say that a package had removed its TypeScript types even though valid declaration files were still included in the published package.

My fix is available in npmx PR #3102.

Bug Fix or Performance Improvement

A package can expose TypeScript declarations explicitly through fields such as types or typings. It can also provide declarations implicitly by placing them beside its JavaScript entry points.

For example:

dist/index.mjs
dist/index.d.mts

TypeScript can use dist/index.d.mts even when package.json does not contain a top-level types field.

npmx already understood this pattern on its package-analysis page. However, the timeline endpoint used hasBuiltInTypes(), which only checked package metadata.

This caused the two parts of npmx to disagree:

The package page correctly showed “Types included.”
The timeline incorrectly showed “TypeScript types removed.”

Code

The fix keeps the fast metadata check as the first step. It performs the more expensive published-file analysis only for visible versions that could be part of a type-removal sequence.

The latest implementation selects every untyped version that has an older typed version somewhere earlier in the package’s history:

const possibleTypeRemovals = visibleVersions.filter(version => {
  if (version.hasTypes) return false

  const versionIndex = allVersions.indexOf(version)
  return allVersions
    .slice(versionIndex + 1)
    .some(previousVersion => previousVersion.hasTypes)
})

Checking the full sequence is important. Consider these versions:

1.0.0 — explicit types field
2.0.0 — colocated .d.mts declaration
3.0.0 — colocated .d.mts declaration

An earlier version of my fix analyzed only 2.0.0, because it was directly beside the metadata transition. The latest version also analyzes 3.0.0 and any other affected version in the sequence.

For each candidate, the timeline fetches the package metadata and published file tree. It then reuses the project’s existing analyzePackage() utility:

const { pkg, typesPackage, files } =
  await fetchPackageWithTypesAndFiles(packageName, version.version)

const analysis = analyzePackage(pkg, {
  typesPackage,
  files,
})

if (analysis.types.kind === 'included') {
  version.hasTypes = true
}

If the additional lookup fails, the endpoint preserves the original metadata-only result instead of failing the complete timeline request.

Tests

I started by running the existing test suite and confirming that all 1,716 tests passed before making changes.

I then added a regression test with three package versions:

1.0.0 declares types explicitly.
2.0.0 publishes index.mjs and index.d.mts.
3.0.0 also publishes index.mjs and index.d.mts.

The test verifies that both implicit versions are analyzed and that all three versions report TypeScript types.

expect(fetchPackageWithTypesAndFilesMock)
  .toHaveBeenCalledWith('my-pkg', '2.0.0')

expect(fetchPackageWithTypesAndFilesMock)
  .toHaveBeenCalledWith('my-pkg', '3.0.0')

expect(result.versions).toHaveLength(3)
expect(result.versions[0]?.hasTypes).toBe(true)
expect(result.versions[1]?.hasTypes).toBe(true)
expect(result.versions[2]?.hasTypes).toBe(true)

I also added a genuine-removal test. In that case, the newer version publishes index.mjs without a matching declaration file, so hasTypes correctly remains unset.

The final validation included:

TypeScript type checking
Repository lint checks
The focused timeline test suite
All 82 unit-test files
The complete unit-test suite with the new regression coverage
GitHub continuous-integration checks

My Improvements

The final change improves the timeline in several ways:

It recognizes colocated .d.mts declarations.
It reuses the existing package-analysis implementation.
It handles consecutive implicit-type versions after a metadata transition.
It preserves genuine “types removed” events.
It avoids failing the entire timeline when an additional file lookup is unavailable.
Its tests verify array length before using optional indexed access.

What I Learned

The main lesson was that package metadata does not always describe everything inside a published npm package. Removing a types field does not necessarily mean that TypeScript support was removed.

I also learned why regression tests should cover a sequence rather than only one transition. Testing just 1.0.0 → 2.0.0 missed the behavior of 3.0.0. Extending the test revealed that every affected version after the transition needed file-aware analysis.

Review feedback also improved the test quality. I replaced non-null assertions on indexed versions with an explicit length assertion and optional access.

Most importantly, I reused npmx’s existing analysis logic instead of implementing another declaration-detection algorithm. This keeps the package page and timeline consistent.

Before and After

Before:

1.0.0 — TypeScript types included
2.0.0 — TypeScript types removed
3.0.0 — TypeScript types not detected

This could appear even when 2.0.0 and 3.0.0 contained valid .d.mts declarations.

After:

1.0.0 — TypeScript types included
2.0.0 — TypeScript types included
3.0.0 — TypeScript types included

A release that genuinely removes both the metadata and the declaration files is still treated as a type removal.

Pull Request

The implementation, tests, and review history are available in npmx PR #3102.

Miso & Memory: A CSS-Illustrated Ramen Landing Page for Rainy Nights

L Anil Kumar Singha — Fri, 31 Jul 2026 05:08:24 +0000

This is a submission for Frontend Challenge — Comfort Food Edition, Perfect Landing.

What I Built

I built Miso & Memory, a landing page for an imaginary late-night ramen counter.

The concept is inspired by the feeling of coming home to a hot bowl after a long, rainy day: slow broth, springy noodles, warm light, and the good kind of quiet.

The visual direction combines editorial typography, an earthy restaurant-inspired palette, Japanese print-inspired details, and a steaming ramen bowl illustrated with custom CSS.

The landing page includes:

A responsive CSS-art ramen hero
Animated steam and a scrolling kitchen-principles banner
A curated menu of comfort bowls
The story behind the imaginary restaurant
An interactive “build your comfort bowl” experience
Dynamic topping selection and price calculation
Keyboard-friendly controls and accessible labels
Visible selected and confirmation states
Reduced-motion support
Responsive mobile, tablet, and desktop layouts

Demo

Open Miso & Memory

Source Code

View the source code on GitHub

Journey

I wanted this landing page to feel handcrafted rather than relying on conventional restaurant photography.

The hero illustration is constructed from CSS shapes, borders, clipping paths, shadows, and animation. The bowl contains noodles, a jammy egg, mushrooms, greens, narutomaki, chopsticks, and rising steam.

One of my favorite parts is how the illustration and interface share the same visual language. The rust-red sun becomes the primary action color, broth-inspired gold highlights selected toppings, and forest green carries through the typography and bowl outlines.

I also wanted the page to be functional rather than purely decorative. Visitors can choose from three bowls, add or remove toppings, see the total update immediately, and save their selection.

The interactive controls use semantic buttons, aria-pressed states, and a status message when the bowl is saved. The page also respects prefers-reduced-motion for visitors who prefer a calmer experience.

The project is built with React, TypeScript, Vinext, Vite, and custom CSS. It is deployed publicly on Cloudflare Workers.

What I Learned

This project reminded me how much atmosphere can be created with a restrained color palette, expressive typography, and carefully composed CSS.

I also learned more about:

Constructing detailed illustrations from CSS primitives
Balancing animation with accessibility
Designing responsive editorial layouts
Building keyboard-friendly selection controls
Deploying a Vinext application and its static assets to Cloudflare Workers

AI Assistance

I used Codex as a collaborative development tool for design exploration, implementation, accessibility improvements, troubleshooting, and deployment guidance.

I reviewed and refined the project’s creative direction, interface, content, and interactions before submitting it. The social-preview image was created using an AI image-generation tool. The ramen illustration visible in the website’s hero section is implemented with CSS.

License

The source code is available under the MIT License.

Thanks for stopping by. Your seat at the counter is waiting. 🍜

Beyond Test Automation

L Anil Kumar Singha — Mon, 27 Jul 2026 15:32:54 +0000

How I Built a Scalable Release Confidence Platform with Playwright, CI/CD, and AI

From a manual regression process to an engineering platform that improved release confidence through deterministic automation, reusable architecture, and AI-assisted coverage analysis.

Introduction

Software engineering becomes harder as software becomes more successful.

Early on, shipping a release is straightforward—few features, a small user base, and limited integration points. Manual verification is practical.

That doesn't last.

New modules ship, workflows interconnect, and changes that appear isolated begin breaking completely unrelated parts of the application.

The problem stops being:

"Write the feature."

It becomes:

Can we deploy today without breaking an existing workflow?
Can we merge changes knowing critical user journeys still work?
Can we tell what isn't being tested before it reaches production?

In our case, the product had grown into a large enterprise application with many interconnected workflows, shipping once or twice every month. Every release depended on completing a full manual regression cycle before deployment.

Regression scenarios lived in spreadsheets and were executed manually across business-critical workflows. Depending on the scope of the release, this consumed nearly an entire working day, followed by additional verification before anyone felt comfortable approving production deployment.

Some releases were delayed for one reason:

Regression wasn't finished yet.

The software was ready.

The pipeline was ready.

Confidence wasn't.

The original objective sounded simple:

Automate manual regression using Playwright.

It didn't stay simple.

Parallel execution exposed shared-state bugs.

Authentication became significantly more complex.

Flaky tests quickly eroded trust.

Maintaining hundreds of scenarios required the same engineering discipline as maintaining any production software system.

Eventually one realization changed the direction of the project.

Passing tests only answers one question.

Did the scenarios we already know about still work?

It does not answer another equally important question.

What important user journeys are we not testing at all?

That realization transformed the effort.

Instead of building a collection of Playwright scripts, we built an internal engineering platform that combined:

Deterministic end-to-end automation
CI/CD integration
Reusable automation architecture
AI-assisted coverage analysis

The AI-assisted coverage analysis agent examines existing Playwright automation, identifies missing business workflows, highlights coverage gaps, and recommends the next scenarios worth automating before those blind spots become production incidents.

This isn't a Playwright tutorial.

It's the engineering decisions, failures, trade-offs, and architectural lessons behind transforming manual regression from a release bottleneck into a system engineers genuinely trust.

The Hidden Cost of Manual Regression

We shipped one to two releases every month.

Development generally finished on time.

Release preparation became the bottleneck.

What initially looked like a manageable checklist gradually evolved into an entire day of validation covering:

Workflow management
Document processing
Search
Approval flows
Authentication
Administrative tooling

...all executed manually before every release, even when only a small feature had changed.

This wasn't a discipline problem.

Manual verification simply doesn't scale.

Every release raised the same questions:

Have we tested every critical workflow?
Did this change silently break another module?
Are we repeatedly testing familiar paths while missing new functionality?
Can we complete regression quickly enough without cutting corners?

Too often, the answer to the last question was no.

Releases slipped.

That experience fundamentally changed how I viewed automation.

Automation isn't about reducing manual effort.

It's about removing release uncertainty.

The real question an engineering platform should answer is:

Can we confidently release this change today?

That became the design principle for everything that followed.

Owning the Platform

There was no dedicated QA or test automation engineer on the team.

Alongside designing and delivering business-critical features, I took ownership of improving release quality by building the automation platform that supported them.

That distinction mattered.

The framework wasn't developed from the perspective of someone testing the application from the outside.

It was designed with an understanding of:

Business workflows
System architecture
Operational constraints
The kinds of failures that mattered most to end users

Building the framework, integrating it into the CI/CD pipeline, improving execution reliability, and evolving it alongside the application happened while continuing normal feature development.

That experience completely changed how I viewed test automation.

It wasn't a collection of Playwright scripts anymore.

It became an engineering platform whose purpose was to improve release confidence through:

Reliable execution
Reusable architecture
Deterministic behavior
Fast developer feedback

Every architectural decision that followed was driven by that objective.

Building the First Automation Framework

Why Playwright?

Its native TypeScript support, automatic waiting, built-in assertions, reliable parallel execution, and excellent debugging capabilities made it a strong foundation for building a maintainable end-to-end testing platform.

One architectural constraint influenced almost every design decision.

The application exposed no dedicated testing APIs for preparing test data or bootstrapping scenarios.

Automation therefore had to interact with the system exactly like a real user.

That meant authentication, fixtures, state isolation, and test data management weren't conveniences.

They became core responsibilities of the framework itself.

Designing around those constraints ensured that automated tests validated real user journeys instead of privileged internal APIs, making the resulting feedback significantly more trustworthy.

Designing for Scale

Writing Playwright tests is easy.

Maintaining hundreds isn't.

From the beginning, the framework separated responsibilities into clear layers:

Configuration
Test suites
Page Objects
Utilities
Fixtures
Test data
Reporting

That separation meant a UI change usually affected one file instead of dozens.

As the suite expanded, maintenance remained predictable instead of becoming exponentially harder.

Business Workflows Over Pages

Rather than organizing tests around screens or UI components, suites were organized around complete business capabilities.

That approach provided several advantages:

Better ownership
Targeted regression execution
Easier failure isolation
Simpler onboarding for new engineers

Each suite validated an end-to-end business workflow rather than isolated button clicks or page interactions.

The framework reflected how users actually interacted with the product.

Reusable Page Objects

Tests interacted with business-level abstractions instead of raw selectors.

Instead of repeatedly locating buttons and fields throughout the suite, implementation details remained encapsulated inside reusable Page Objects.

That separation kept test cases focused on business intent.

When the UI changed, updates were usually confined to a single location instead of requiring widespread modifications across hundreds of tests.

The result was cleaner code, improved readability, and dramatically lower maintenance costs.

Shared Fixtures

Common setup was centralized across the framework, including:

Authenticated browser contexts
Test data preparation
Browser configuration
Shared fixtures

Beyond reducing boilerplate, this guaranteed that every test started from a predictable environment.

As the automation suite grew, that consistency became one of the biggest contributors to execution reliability.

Authentication as Framework Architecture

Authentication wasn't treated as something every individual test should perform.

Instead, it became part of the framework itself.

Authenticated contexts were reused where appropriate, reducing repetitive setup while improving execution speed.

More importantly, separating authentication from business validation reduced instability once tests began executing concurrently.

Authentication became infrastructure rather than test logic.

Reporting Built for Investigation

Knowing that a test failed isn't enough.

Engineers need to know why.

The framework generated rich debugging artifacts for every execution, including:

HTML reports
Playwright traces
Execution logs
Failure screenshots

Instead of reproducing failures locally, engineers could often identify root causes directly from the CI pipeline.

Investigation became significantly faster, allowing teams to spend more time fixing problems than reproducing them.

The initial results were encouraging.

Manual regression effort dropped significantly.

Test execution became repeatable.

Releases gained a much more reliable validation process.

But as the automation suite continued growing—and parallel execution increased—a completely different class of problems appeared.

Interestingly, those problems weren't in the application.

They were inside the automation framework itself.

When Scaling Broke Everything

Parallel execution changed everything.

Running tests concurrently reduced execution time dramatically—but immediately exposed assumptions nobody had questioned.

Tests that had always passed in sequential execution suddenly began failing intermittently.

Same suite.

Same code.

Different outcome.

That inconsistency was the first indication that the automation framework—not the application—needed architectural improvements.

Flaky Tests Kill Trust Fast

Once a test can pass, fail, and then pass again without any application changes, every failure creates the same question:

Is the application broken, or is the test broken?

If engineers can't answer that confidently, automation quickly loses credibility.

Reliability isn't simply a nice-to-have.

It's the foundation that determines whether developers trust automated regression enough to make release decisions based on it.

Root Cause: Shared State

The biggest issue turned out to be shared state.

Parallel workers were unintentionally interacting with common resources.

Tests assumed:

Data created by previous executions still existed.
Application state would remain unchanged throughout the suite.

Both assumptions broke under concurrent execution.

Instead of adding retries, the framework introduced stronger isolation between test runs so each scenario could execute independently.

Isolation—not retries—became the long-term solution.

Authentication Under Load

Authentication became another scaling challenge.

Initially, authenticated sessions were reused across multiple workers.

That worked until concurrency increased.

Multiple workers sharing authentication contexts introduced unpredictable session behavior that appeared completely random during execution.

The solution wasn't adding more login steps.

It was treating authentication as framework architecture rather than business logic.

Authentication became infrastructure.

Business validation remained inside the tests.

That separation improved both execution speed and reliability.

Timeouts Were Symptoms, Not Problems

Increasing timeout values is one of the easiest ways to make unstable tests appear reliable.

It's also one of the easiest ways to hide real problems.

Whenever a timeout occurred, the first question was never:

Should we increase the timeout?

Instead, the investigation focused on the underlying cause.

Was the application genuinely slow?

Was a selector unstable?

Was another worker interfering?

Was the test depending on stale data?

Fixing those issues produced a far more reliable framework than simply increasing timeout values.

Scaling Without Guesswork

As the suite continued growing, another pattern emerged.

Increasing the number of parallel workers increased contention on shared backend resources—particularly database connection pools.

Interestingly, latency didn't grow linearly.

Doubling worker count didn't double execution time.

Instead of relying on arbitrary timeout values, timeout budgets were tuned using observed execution characteristics.

The objective wasn't making tests pass.

It was ensuring failures remained meaningful.

That distinction changed how the framework evolved.

Engineering effort shifted from masking failures to eliminating the reasons they occurred.

Why Retries Weren't the Answer

Many automation frameworks rely on retries.

If a test fails, run it again.

That approach can improve pass rates, but it often hides the real problems:

Race conditions
Shared state
Timing assumptions
Unstable selectors

A green pipeline doesn't necessarily mean a reliable test suite.

It may simply mean the framework retried enough times to hide the instability.

Instead of increasing retries, the objective was to eliminate the reasons retries were needed in the first place.

That required architectural changes—not additional assertions.

The framework was redesigned for deterministic parallel execution, introducing stronger isolation between concurrent test runs and a clearer separation between shared setup and business validation.

Authentication, fixtures, and test state were managed so that one test could no longer influence another, even under heavy concurrency.

As execution became deterministic, retries gradually stopped providing meaningful value.

Instead of masking intermittent failures, the framework consistently surfaced genuine issues, allowing engineers to fix root causes rather than chase flaky tests.

The broader lesson was clear.

Large-scale automation problems are usually software engineering problems.

Solving them required architecture:

Clear isolation boundaries
Reusable abstractions
Reliable fixture management
Predictable execution

—not simply writing more assertions.

From Stability to Coverage: AI-Assisted Coverage Analysis

Even after building a fast and reliable automation platform, one question remained unanswered.

How do we know which important workflows aren't being tested at all?

Execution quality had improved.

Coverage quality was still largely a guess.

That realization led to building an AI-assisted coverage analysis agent.

Instead of simply answering:

"Did the tests pass?"

the platform could now answer:

"What are we still not testing?"

The objective wasn't generating tests automatically.

The objective was helping engineers make better decisions about where automation effort should go next.

Design Principles

AI Assists. Engineers Decide.

The agent doesn't generate automation autonomously.

Instead, it:

Identifies blind spots
Detects missing business workflows
Suggests high-value scenarios

Engineers remain responsible for reviewing and implementing those recommendations.

Decision-making stays transparent and accountable.

Business Workflows Over UI Elements

Counting pages, buttons, or components says very little about release confidence.

Instead, the analysis focuses on complete business journeys.

The objective is measuring workflow coverage—not interface coverage.

That ensures the scenarios users actually depend on are represented inside the automated suite.

Explainable, Not Opaque

Every coverage classification—

Covered
Partially Covered
Not Covered

can be traced back to observable application behavior and existing Playwright automation.

Nothing is hidden behind a black-box score.

Engineers can validate every recommendation before acting on it.

Actionable Over Informational

Reports don't simply describe the current state.

They prioritize uncovered workflows by estimated business impact and recommend the next scenarios worth automating.

The goal is reducing engineering decision fatigue—not generating another dashboard.

Deterministic Output

Running the analysis twice against the same application and the same automation suite should produce identical conclusions.

Recommendations should change only because the application changes—not because the analysis is inconsistent.

Continuous, Not One-Time

Coverage isn't something you "finish."

Every feature changes the application's risk profile.

The question evolves from:

"Have we completed automation?"

to:

"What should we automate next to reduce release risk?"

Current Limitations

The coverage analysis agent deliberately has a narrow responsibility.

It does not:

Execute Playwright tests
Determine whether application behavior is correct
Replace engineering judgment

Instead, it analyzes the relationship between:

Expected business workflows
Existing Playwright automation

Its effectiveness depends on well-structured Playwright projects, meaningful test names, reusable page objects, and clearly defined business workflows.

It's a decision-support system—not a quality certification.

For business-critical functionality, human review remains essential.

Continuous Quality in CI/CD

The framework delivered its greatest value once it stopped depending on someone remembering to run it manually.

Instead, it became part of the delivery pipeline itself.

Integrated into GitLab CI/CD, every meaningful change executed the same deterministic regression suite before moving forward.

The biggest mindset shift wasn't technical.

It was moving from asking:

"Has regression been run?"

to asking:

"Did regression pass?"

That seemingly small change fundamentally altered how release decisions were made.

The pipeline provided:

Standardized execution — Every run used the same browser, configuration, assertions, and reporting, eliminating "works on my machine" inconsistencies.
Parallel execution — Runtime remained practical even as the suite grew, without sacrificing isolation.
Fail-fast behavior — Critical failures stopped the pipeline early instead of wasting time executing an already-failed build.
Rich debugging artifacts — HTML reports, Playwright traces, logs, and screenshots made most failures understandable directly from CI without reproducing them locally.

Regression stopped being a checklist.

It became a deployment gate alongside build validation and code quality.

Passing the pipeline no longer meant:

"The project compiles."

It meant:

"Critical business workflows continue to work."

Counterintuitively, adding more automation actually accelerated delivery.

Less manual verification.

More predictable releases.

Release decisions backed by evidence instead of intuition.

Measuring the Impact

Several hundred end-to-end scenarios that previously required nearly an entire working day of manual validation now execute automatically within minutes as part of every meaningful CI run.

The impact wasn't simply faster execution.

It fundamentally changed how the team approached release quality.

Repeatable Outcomes

Regression results no longer depended on:

Who executed the tests
How much time remained before release
Individual interpretation

Every execution followed the same deterministic process.

Faster Investigation

Rich debugging artifacts—including Playwright traces, execution reports, logs, and screenshots—made it possible to understand most failures directly from the CI pipeline.

Instead of spending time reproducing issues locally, engineers could begin fixing problems immediately.

Measurable Confidence

Release readiness was supported by:

Validated business workflows
Reproducible failures
Reviewable reports
Coverage analysis

Confidence became measurable instead of subjective.

From Reactive to Proactive Quality

Instead of repeatedly asking:

"Why did this break?"

the conversation increasingly became:

"What important workflows are still missing from automation?"

That shift transformed automation from a validation activity into a continuous engineering practice.

Lessons Learned

Building this platform changed how I think about software engineering—not just test automation.

Several lessons continue to influence how I design systems today.

1. Automation Is Software

Automation deserves the same engineering discipline as production code.

It needs:

Modular architecture
Code reviews
Reusable abstractions
Continuous refactoring

—not simply more scripts.

2. Reliability Beats Quantity

A small automation suite that engineers trust creates more value than hundreds of unreliable tests.

Determinism matters more than raw test count.

3. Fast Feedback Changes Engineering Behavior

Slow regression gradually gets ignored.

Fast, deterministic regression integrated into CI becomes part of every engineering decision.

The faster feedback arrives, the earlier problems are discovered.

4. Coverage Matters More Than Test Count

Hundreds of green tests don't necessarily mean important workflows are protected.

Understanding what isn't covered is often more valuable than knowing what already is.

That's exactly the problem the AI-assisted coverage analysis agent was designed to solve.

5. AI Should Augment Engineering Judgment

The goal wasn't replacing engineers.

The goal was accelerating analysis, surfacing blind spots, and helping teams prioritize automation work more effectively.

Engineering decisions remained human.

6. Quality Is Continuous

Quality isn't something added before a release.

Every feature changes the application's risk surface.

Automation must evolve continuously alongside the software itself.

7. Confidence Is the Real Deliverable

The most valuable outcome wasn't:

Playwright
CI/CD integration
Parallel execution
Reporting
AI

Those are implementation details.

The real deliverable was enabling engineers to make release decisions based on evidence instead of intuition.

Conclusion

The original goal was straightforward.

Automate manual regression.

What ultimately emerged was something much broader.

It demonstrated that quality engineering is fundamentally a software engineering discipline—not a separate track.

This wasn't work performed instead of building the product.

It came directly from building it.

Understanding the application's architecture, business workflows, and operational constraints made it possible to design an automation platform that remained reliable, maintainable, and scalable as the product evolved.

The platform combined:

Deterministic automation
Parallel execution
Reusable architecture
CI/CD integration
Rich debugging artifacts
AI-assisted coverage analysis

But the most important outcome wasn't the technology.

It was changing how release decisions were made.

Replacing intuition with evidence.

Automation tells you what you already know still works.

Coverage analysis tells you what you've overlooked.

Both are necessary.

Together, they provide a stronger foundation for release confidence than either could alone.

Looking ahead, there are still opportunities to push quality engineering further:

Risk-based regression selection
Historical coverage trend analysis
Pull request–level coverage impact reports
AI-assisted test maintenance
Flaky-test detection
Visual regression
Requirement-to-test traceability

These are areas I'd like to continue exploring as software systems—and the expectations around software quality—continue to evolve.

If you've built something similar, or approached release confidence differently, I'd genuinely love to hear about it. Let's connect and discuss.

How to add watermark on an image in Laravel 5.8 Step by Step

L Anil Kumar Singha — Tue, 04 Aug 2020 06:46:41 +0000

In this blog post, we will learn, how to add watermark to an image in Laravel 5.8 application, to add watermark to images we will use the intervention image composer package in Laravel 5.8. we can add images or text as a watermark on the image in Laravel. For more docs, you can follow them.
Intervention Image.

To make a watermark on an image. we will install intervention/image package and then we will create one simple route to adding image watermark in the Laravel app. so let’s follow the below step to add image watermark in Laravel 5.8.

Step:1 Install intervention/image Package.

In the first step, I install an intervention/image composer package for adding watermark to the image in Laravel 5.8. to install a package using the following command.

composer require intervention/image
After installation, we need to set providers and alias, to do that we need to follow some steps… go to your project and search.

config/app.php

‘providers’ => [
Intervention\Image\ImageServiceProvider::class
]
‘aliases’ => [
 ‘Image’ => Intervention\Image\Facades\Image::class
]

Step:2 Add Watermark to image

Here, I created a controller(you can use a simple route) to add a watermark to the image. so you need to add two images on your public “images” folder for testing purposes.

Here I use two images one for the main image and a second image for watermark so I have a main.png and watermark.png image on your images folder for demo.

public function addWatermark(){
   $img = Image::make(public_path('images/main.png'));    
   $img->insert(public_path('watermark.png'),'bottom-right',10, 10); 
   $img->save();
}

So here we completed tutorials on How to Add Watermark on an Images in Laravel 5.8 step by step.