DEV Community: BRUNO SOUZA

The Autism Stats In The Tech Industry And The Real Hiring Problem

BRUNO SOUZA — Wed, 26 Aug 2026 13:05:42 +0000

You have seen the slide. Someone at a conference puts up "autistic employees are 140% more productive," the room nods, and everyone goes back to running the same 45-minute whiteboard interview that filtered those people out three years ago.

I went looking for the source of that number, and of the four or five others that circulate with it. Most of them do not survive contact with a search engine. That bothers me because the underlying problem is real and well documented, and propping it up with marketing statistics makes it trivially easy for a sceptical engineering manager to dismiss the whole conversation.

So: what actually holds up, and what should you change on Monday?

The numbers that fall apart

"Autistic employees are 140% more productive." This traces back to JPMorgan Chase's Autism at Work pilot in 2015. The pilot was a handful of people, four or five depending on which account you read, in one back-office role, measured over six months against colleagues who had been doing the same job for three to ten years. The headline figure from that cohort was 48% faster. The 90–140% range comes from internal claims about specific roles, reported second-hand, never published, never peer reviewed. Four or five people. One task type. No control for the fact that the pilot hires were screened for exactly that task.

It is still spreading. Pull up any "neurodivergent hiring in 2026" listicle, and the 90–140% claim is right there, sourced to nothing.

Quote it in a pitch to a CFO and the first person in the room who checks will win the argument, and they will win it against your entire point.

"3.7% of developers are autistic, versus 1% of the population. Four times overrepresented." The 3.7% comes from a US developer portal called Developer Pitstop, repeated by auticon, and then into everyone's slide deck. Stack Overflow's own 2020 survey put it at 2.3%. Both are self-selected samples of people who answer developer surveys, and as far as I can tell Stack Overflow has not published a neurodiversity breakdown since 2022.

The denominator is worse. The CDC's most recent ADDM data puts prevalence at 1 in 31 eight-year-olds, about 3.2%, up from 1 in 36 in the previous cycle (MMWR Surveillance Summaries, April 2025, using 2022 surveillance data). Diagnosis rates in adults are lower mainly because nobody was screening adults thirty years ago.

If you are hiring in Ireland, there is now a local denominator. The CSO's Irish Health Survey 2025, published in May 2026, found that 7.7% of males aged 15 to 24 have an autism diagnosis, against 4.5% of females, and that 38.2% of women in that age band report a diagnosed or suspected neurodivergent condition. Those are the people entering your graduate pipeline.

So the "four times" multiplier compares a self-reported developer figure against a general-population figure that has roughly tripled since the comparison was first written down. Drop the multiplier. It is doing no work for you.

"Only 22% of autistic adults in the UK are in paid work." Stale rather than fabricated: that was ONS data from 2021, and the House of Commons Library now puts it at 34.0% for 2024/25, against 55.3% for all disabled people and 82.0% for non-disabled people. Still the worst rate of any disability group, so the current number makes your case without you having to be five years out of date.

"Up to 85% of autistic people in Ireland are unemployed or underemployed." This one is closer to home, and it is the Irish version of the same problem. It appears in AsIAm campaign material, in the Insurance Ireland employer charter, and in the September 2025 coverage of the Ibec and AsIAm Roadmap for Autism and Employment, usually as "up to 85%" or "over 80%," attributed to "global research." I have not been able to find the study. What is on the record: Ireland's disability employment rate is 32.6%, roughly 20 points below the EU average, and CSO figures quoted in Irish coverage put 16% of autistic people in full-time work and 32% in some form of paid work. Different claims, different denominators. If you use the 16/32 split, link the CSO release rather than a press piece.

The numbers that survive

The employment gap is the finding, and it replicates. 34% employment against 82% for non-disabled adults, with the Buckland Review (February 2024) adding that autistic graduates are twice as likely to be unemployed 15 months after finishing as non-disabled graduates. Only 36% are in full-time work in that window, from the AGCAS What Happens Next? 2022 data. Graduates. People who already cleared a technical degree.

The pay gap survives too, and it is the number I would put next to the employment one: autistic employees earn around 27.9% less than non-disabled colleagues, the widest gap of any disability group in the UK data.

The desire to work is there: the National Autistic Society's figure of 77% of unemployed autistic people wanting a job has held up across surveys for a decade.

The interview is a measurable choke point. The number everyone reaches for here, 11% of applicants who disclosed on their application were offered any interview adjustment and 3% an alternative process, comes from the NAS surveys of 2016, restated in a 2025 editorial in Autism by NAS's Tim Nicholls. Say 2016 when you quote it. The current comparative work is Davies et al. (2023) in Autism 27(6), which compared autistic, other neurodivergent and neurotypical adults' experiences of UK hiring processes directly.

Better than either, there is an actual experiment. Maras et al. (2021), also in Autism, put 50 adults, 25 autistic and 25 not, through two mock interviews six months apart. Employment experts blind to diagnosis rated the answers. In the first round, the autistic candidates were rated less favourably. In the second round, with questions rewritten to ask explicitly for specific details and examples rather than expecting the candidate to infer what was wanted, ratings improved for everyone, improved most for the autistic candidates, and the gap narrowed. That is a controlled result about a change you can ship this week, and it beats any productivity anecdote.

The cost objection is dead, but check which edition of the JAN report you are quoting, because I got this wrong myself. JAN surveyed 26,028 employers who contacted it between 2019 and 2024 and received 5,406 responses. Of the 1,425 who gave cost data, 61% said the accommodation cost nothing, 33% had a one-time cost with a median of $300, and 6% had an ongoing cost with a median of $2,400 a year (report updated September 2025). The $3,750 annual figure in circulation is from the previous edition covering 2019 to 2022. Both were right for their vintage. Only one is current.

On the strengths side, be careful. The peer-reviewed work points the other way. Verma, Cruz and Liebel analysed the 2022 Stack Overflow survey, comparing professional engineers with autism (n=374), ADHD (n=1,305) and dyslexia (n=363) against neurotypical engineers, and found that neurodivergent engineers report more difficulty at work. Superhuman output does not show up in the data. The paper appeared as a preprint in June 2025 and was published at SEAA 2025 (Springer LNCS 16083), so you can now cite it as reviewed work rather than as an arXiv drop. Alongside it, Gama, Liebel and colleagues published a grounded-theory study at ICSE-SEIS 2025 on how cognitive dysfunctions affect the performance of developers with ADHD and autism, which is the closest thing we have to a mechanism rather than a vibe.

Interview studies with autistic software engineers do consistently surface pattern recognition, sustained focus and tolerance for detail work as real strengths. They also surface a finding people skip: communication difficulty extends into the code itself, into naming, abstraction boundaries and comments, and not only into standups.

The honest argument for hiring is that the process you use to reject people is broken. The productivity dividend framing turns a person into a line item, and it collapses the moment someone has an average quarter.

What to change in the loop

Everything below is free, and most of it improves your signal on every candidate you interview. That last part is not a hopeful aside: it is what Maras et al. found, since the adapted questions lifted the non-autistic candidates too.

Send the questions in advance. The technical content of your interview is not a secret worth protecting. You are testing whether someone can build software, not whether they can recover from ambush.
Ask for what you actually want. Instead of "tell me about a challenge you faced," ask for the situation, what you personally did, and what the measurable outcome was. This is the single adaptation with experimental support behind it.
Offer a take-home or a pairing session as a stated alternative, on the job ad, before anyone has to ask for it. Asking for an adjustment costs the candidate a disclosure they may not want to make.
Split a four-hour loop into two shorter sessions on different days. Sensory and social load compounds; hour four is measuring stamina.
Kill the "culture fit" round, or define it against written behaviours. Unstructured chat over coffee is a similarity test with a job title.
State the format up front: who is in the room, how long, what you will ask, whether cameras are expected.

Day to day, the changes that matter are boring: agendas before meetings, decisions written down after them, explicit deadlines instead of "when you get a chance", async by default, and a real quiet space or a genuine remote option rather than a hot desk beside the sales floor.

One artefact I would steal outright. Frank Ray, a UK engineer diagnosed at 40 after twenty years of contracts ending badly, published a "How we work" document for his clients and found it attracted better clients rather than fewer. Put one in your repo:

# How this team works

## Communication
- Slack is async. No reply expected within the hour.
- Anything decided in a call gets written into the ADR or the ticket. If it isn't written, it wasn't decided.
- @here is for production incidents.

## Meetings
- Agenda in the invite or the meeting is declined, no offence taken.
- Cameras optional. Always.
- No surprise attendees.

## Work
- "Urgent" means today. Say the date otherwise.
- Code review is about the code. Suggestions are prefixed `nit:` when optional.
- Deep work blocks in the calendar are load-bearing. Don't book over them.

None of that is an autism accommodation. It is how a functioning distributed team already operates, which is the point. The adjustments that get labelled special are mostly competent engineering management applied consistently.

The Irish and EU angle nobody puts on the slide

The research above is overwhelmingly American and frames everything around the ADA, which is useless to you if you are hiring in Dublin. Here the framework is section 16 of the Employment Equality Acts 1998–2015, and it is a positive duty: appropriate measures, unless they impose a disproportionate burden. It covers job applicants, not only employees. The governing authority is the Supreme Court in Nano Nagle School v Daly, which held that duties can be stripped out of a role as an accommodation, while also making clear that the duty is not infinite.

The WRC reads the disproportionate-burden defence narrowly, and the recent decisions are worth knowing:

Mary Tracy v Smurfit Kappa Ireland (Edco), January 2025. €64,000 across two decisions, largely for never exploring or discussing accommodations at all. IHREC provided the legal representation. Tracy herself had pointed out to her employer that state funding was available.
Paul Hill v Department of Social Protection, April 2026. €30,000, with discrimination found across a twelve-year period. The Department that lost is the one that administers the State's own workplace accommodation programme.
Lukasz Swiercz v Lidl Ireland, ADJ-00059764, April 2026. €28,000 for refusing a return to work on light duties.

The exposure is real: compensation runs up to two years' remuneration or €40,000, whichever is greater.

And the Irish cost objection has a state answer that no American report can give you. Work and Access, which replaced the Reasonable Accommodation Fund and the Disability Awareness Support Scheme, funds a workplace needs assessment up to €2,500, workplace adaptation up to €25,000, and disability equality and inclusion training up to €20,000, with an equipment grant on top. Private sector only, and the public sector is excluded, which is its own conversation.

I wrote that up separately, because it deserves more than four paragraphs: Reasonable Accommodation in Irish Tech: What Section 16 Actually Requires.

The part senior engineers get wrong

There is a trap on the other side of hiring that the corporate programme pages never mention. Sustained focus produces output, output gets praised, and an autistic engineer can spend three years being the person who ships while quietly missing that promotion to staff runs on influence, disagreement handled well, and knowing which meeting to be in. Managers who benefit from the output rarely volunteer this. Burnout arrives before the title does.

If you manage someone like this, say the promotion criteria out loud, in writing, with examples. The implicit ones are the whole barrier.

What I actually want to know: has anyone reading this changed their interview loop and measured what happened to the pipeline? Or dropped the whiteboard round and found the signal got better? I have opinions about which of the changes above matter most, and almost no data on which ones teams actually keep after six months.

Bruno Souza
Senior Backend Engineer, Dublin

The Singularity Is Nearer: What Ray Kurzweil's Six Epochs Gets Right About Our Future

BRUNO SOUZA — Mon, 30 Mar 2026 22:15:04 +0000

Some people say the current AI bubble will soon burst and that AI is not intelligent enough to produce the singularity. Others claim we are very close, or even that we have already achieved AGI. But if AGI is destined to be created, where exactly are we in that process right now?

Trying to find an answer, or at least a sharper mental model, I've been reading Ray Kurzweil's *The Singularity Is Nearer, his long-awaited follow-up to *The Singularity Is Near (2005). At its heart, the framework is something every engineer in the AI era should understand.

Kurzweil structures the entire history and future of intelligence into Six Epochs. Each epoch represents a qualitative leap in how information is processed from the physics of atoms to a universe fully saturated with intelligence. It sounds ambitious, but he grounds it in the same empirical trends that have driven tech progress for decades.

As a software engineer who's watched distributed systems, cloud computing, and now LLMs reshape what's possible in just a few years, I find this framework surprisingly useful as a mental model.
Let's break it down.

The Law of Accelerating Returns (Quick Intro)

Before diving into the epochs, you need to understand the engine driving all of them: the Law of Accelerating Returns.

The idea is simple: technological and evolutionary progress is not linear. It's exponential. Each innovation builds on previous ones, compounding over time. The doubling of transistor density, the cost curves for compute, the trajectory of LLM capabilities — these aren't coincidences. They reflect a deep underlying dynamic.

But there's a second, equally important principle that structures the epochs themselves:
indirection. Each epoch doesn't just follow the previous one; it uses the mechanisms of the previous one as raw material to bootstrap the next. Evolution creates DNA; DNA creates brains; brains create technology; technology creates the merger. The epochs are not a list. They're a compounding chain.

Kurzweil has been tracking these curves since the 80s. The exponential trends he described in 2005 have, remarkably, held.

Epoch 1 — Physics and Chemistry

Information encoded in the structure of matter itself.

The story starts at the origin: atoms and molecules, patterns of matter and energy. The laws of physics, quantum mechanics, thermodynamics, and electrochemistry govern how matter
self-organises.

Kurzweil's point here is subtle: even at this level, the universe isn't random. The fine-tuned physical constants that allow stable atoms to exist, and enable carbon, hydrogen, nitrogen, and
oxygen bonding in complex ways represents the first layer of information in the universe.

This raises an uncomfortable question: why are our universe's physical constants so perfectly calibrated for complexity to emerge? Some invoke a divine hand. Others point to the anthropic
principle. Only in a universe that permitted our evolution would we be here to ask the question.

Kurzweil raises the multiverse theory as a parallel lens: if new universes are constantly generated, each with different rules, most would collapse or stagnate without producing anything
interesting. Ours happened to have exactly the right parameters for increasing order and complexity to take hold. We're the universe that made it.

No code yet. No DNA. Just physics creating the conditions for everything that follows.

Epoch 2 — Biology and DNA

The universe invents self-replicating, evolvable information storage.

This is where it gets interesting for engineers. DNA is, in essence, a digital information system: a four-letter alphabet (A, T, G, C — Adenine, Thymine, Guanine, Cytosine) that
encodes the instructions for building and operating living organisms.

Evolution is the algorithm. Slow, blind, but astonishingly effective over billions of iterations. It's gradient descent without a loss function you designed. It optimises for survival and reproduction, producing extraordinary complexity from simple rules.

The key innovation of Epoch 2 isn't just life, it's self-improving information. A system that can modify itself across generations without conscious direction.

Epoch 3 — Brains

Real-time cognition enters the picture.

Epoch 3 is where indirection becomes visible. DNA-guided evolution produced organisms that could detect information through their own sensory organs, and process and store it in their own brains and nervous systems, built entirely on the molecular machinery of Epoch 2, but now operating independently of it.

The third epoch began with early animals' ability to recognise patterns, a capacity that still accounts for the vast majority of brain activity. The human brain (~86 billion neurons, ~100
trillion synaptic connections) added something further: the ability to build abstract mental models of the world, contemplate alternatives, and act on those simulations. We can redesign
reality in our minds before touching it.

But Kurzweil is clear-eyed about the brain's limits. It was shaped by evolutionary pressures, not intentional engineering. It's riddled with cognitive biases, constrained memory, slow learning, and inevitable physical decay. The brain is powerful, but it's also the bottleneck.

And that last capability — abstract modelling, rational contemplation, and the ability to act on ideas — is precisely what triggers the next epoch.

Epoch 4 — Technology

Where we came from (and where we still partly are).

Kurzweil is direct about the link: rational abstract thought, combined with the physical ability to manipulate the world, ushered in the fourth epoch. Technology is Epoch 3's output, built
from Epoch 3's tools, now evolving on its own exponential curve.

This epoch begins with the first tools and accelerates through writing, mathematics, the printing press, the transistor, the internet, and now AI.

The defining feature: technology compounds on itself. Unlike biological evolution, each generation of tools enables faster creation of the next. Exponential curves don't just apply to Moore's Law; they also show up in compute costs, memory density, bandwidth, and, increasingly, model capability.

Kurzweil frames Epoch 4 as the era in which technology is an external capability. Tools that extend what humans can do, but remain clearly separate from human cognition. By that definition,
most of the 20th century sits squarely here.

But the tools we're building are starting to blur the line between "external tool" and "cognitive collaborator". And that distinction is exactly what Epoch 5 is about.

Epoch 5 — The Merger of Human and Machine Intelligence

The Singularity. And arguably, it has already started.

This is the one everyone has heard of and the one most often misunderstood.

Kurzweil projects the full merger of human and artificial intelligence to unfold through the 2030s and 2040s, with AI reaching human-level general intelligence around 2029. In the strictest definition, Epoch 5 is about physical integration: brain-computer interfaces, nanobots operating at the neuronal level, and the boundary between biology and computation becoming irrelevant at the hardware level.

By that definition, we're not fully there yet.

But here's the honest question: Does the merger have to be physical to be real?

Kurzweil's own answer, buried in the book, is revealing. Alongside brain-computer interfaces and nanobots, he gives significant weight to virtual worlds as a vector for the merge between human and machines, the immersive digital environments where human consciousness doesn't just interact with AI but increasingly inhabits spaces populated, shared, and shaped by it. That's a different path to Epoch 5 than biological integration, but in his framework, it's equally valid. The merger happens through presence and immersion, not only through hardware in your skull.

That reframes the question entirely. It's not physical vs. non-physical. It's about how many vectors the merger is travelling along simultaneously.

Consider what's already happening. Engineers using AI to reason through architecture decisions. Researchers are compressing years of literature review into hours. Doctors using LLMs for
differential diagnosis. And beyond knowledge work: people spending meaningful portions of their cognitive and social lives inside AI-populated digital environments, like games, virtual workspaces,
and persistent AI companions. That's not the tooling in the Epoch 4 sense. That's functional cognitive extension across multiple fronts.

The epochs don't have clean start dates. Epoch 3 didn't begin on a Tuesday morning, and the merger is likely the same: not a switch that flips in 2029, but a transition we're already inside, advancing on several tracks at once.

The biological integration piece is nascent (Neuralink, cochlear implants, advanced prosthetics). The virtual integration piece is further along than most people acknowledge. And the functional cognitive merger, especially for knowledge workers, is arguably already a daily reality.

My read: we're in the overlap zone. Late Epoch 4 bleeding into early Epoch 5, through multiple converging paths. The infrastructure of the merger is being built right now by people
like us, the software engineers.

Epoch 6 — The Universe Wakes Up

The most speculative, and the most philosophically significant.

Having merged with technology and mastered intelligence on Earth, the civilisation emerging from the Singularity begins to expand outward, converting matter and energy throughout the cosmos into increasingly sophisticated computational substrate. Indirection operates at a universal scale.

The universe began as simple physics. It evolved through chemistry and biology, producing minds capable of comprehending it. In Epoch 6, those minds that had vastly expanded began to fulfil that potential beyond the edges of a single planet.

Kurzweil acknowledges the speed of light as a hard constraint and concedes this epoch involves genuine unknowns. But his argument follows the same logic as the rest: a universe in which information complexity has increased exponentially at every prior level doesn't simply stop here.

Why This Framework Matters to Engineers

You don't have to buy every prediction to find the Six Epochs useful. What it offers is a macro-level mental model for understanding where we are in the arc of technological progress
and more practically, what we're actually building toward.

We're at the threshold. The messy, ambiguous overlap between technology as an external tool and technology as a cognitive extension. The distributed architectures, AI inference pipelines, and real-time data platforms we're building today are the substrate on which the full Epoch 5 merger will run.

A few questions worth sitting with:

If the functional merger is already underway for knowledge workers, what does that mean for how we design systems?
Are we building for users, or for human-AI composites?
What responsibilities come with being engineers at this particular inflexion point?

Kurzweil's track record is imperfect, but the trends he identified are real. Whether the Singularity arrives on his exact timeline or not, the direction of travel is hard to argue with, and if you're reading this, you're probably already living in its early chapters.

Have you read The Singularity Is Near or The Singularity Is Nearer? Where do you think we actually are? Late Epoch 4,
early Epoch 5, or genuinely in the overlap? Curious what engineers here make of the distinction.

Drop your thoughts in the comments.

How to Install the AWS CLI and Configure It with IAM Identity Center (SSO)

BRUNO SOUZA — Mon, 16 Mar 2026 09:30:00 +0000

Before you can run a single aws s3 command, two things need to be in place: the CLI installed on your machine and credentials configured. So, AWS knows who you are.

This post covers both (CLI and credentials) in the following OS's: macOS, Linux, and Windows. And uses IAM Identity Center (formerly AWS SSO) for authentication. That means short-lived, automatically refreshed credentials instead of long-lived access keys stored in a plain-text file on your disk.

Why IAM Identity Center instead of `aws configure`?

The classic aws configure flow creates a ~/.aws/credentials file with a permanent AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Those keys never expire on their own. If they leak through a committed .env file, a misconfigured S3 bucket, or a compromised machine, the window of exposure is unlimited.

IAM Identity Center issues short-lived session tokens instead. When the session expires, the credentials stop working. You re-authenticate through your browser, and a fresh token is cached locally. It is a fundamentally safer model, and it is what AWS now recommends as the default for developer access.

Prerequisite: Your AWS account must have IAM Identity Center enabled. If you are working with a personal account, you can enable it in the IAM Identity Center console. If you are at a company, your AWS administrator will give you a start URL and the name of your permission set.

You can find the link for the IAM Identity Center in the bottom left corner of the IAM page:

Step 1 — Install AWS CLI v2

macOS

The recommended approach for macOS is Homebrew. It handles updates automatically and keeps the binary on your PATH without any manual symlinking.

brew install awscli

If you prefer the official .pkg installer instead:

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Linux (x86_64)

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

For ARM64 (e.g. AWS Graviton, Raspberry Pi):

curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

If unzip is not installed: sudo apt install unzip (Debian/Ubuntu) or sudo yum install unzip (Amazon Linux/CentOS/RHEL).

Windows

Open PowerShell as Administrator and run:

Invoke-WebRequest -Uri "https://awscli.amazonaws.com/AWSCLIV2.msi" -OutFile "AWSCLIV2.msi"
msiexec.exe /i AWSCLIV2.msi /quiet

Alternatively, download and run the .msi installer manually from https://awscli.amazonaws.com/AWSCLIV2.msi.

Verify the installation

On all three platforms:

aws --version

Expected output (version numbers will vary):

aws-cli/2.27.41 Python/3.11.6 Linux/6.1.0 botocore/2.0.0

If the command is not found, restart your terminal. On Windows, open a new PowerShell or Command Prompt window.

⚠️ WARNING: aws configure sso only works with AWS CLI v2. If aws --version shows aws-cli/1.x.x, you are on v1 and need to upgrade before continuing.

Step 2 — Gather your IAM Identity Center details

You need two values before running the setup wizard:

Value	Where to find it
SSO Start URL	IAM Identity Center console → Dashboard → Issuer URL (or ask your AWS admin)
SSO Region	The AWS region where IAM Identity Center is enabled (e.g. `eu-west-1`)

You can also find both by signing in to your AWS access portal, selecting your permission set, clicking Access keys, and choosing the IAM Identity Center credentials tab.

Step 3 — Configure a profile with `aws configure sso`

Run the interactive wizard:

aws configure sso

You will be prompted for the following. Use the values you gathered above:

SSO session name (Recommended): my-dev-session
SSO start URL [None]: https://d-xxxxxxxxxx.awsapps.com/start
SSO region [None]: eu-west-1 
SSO registration scopes [sso:account:access]: sso:account:access

The CLI will open your browser to complete authentication. Once authorised, it returns to the terminal and asks for a few more values:

AWS account ID: 123456789012
Role name: PowerUserAccess
CLI default client Region [None]: eu-west-1
CLI default output format [None]: json
CLI profile name [PowerUserAccess-123456789012]: my-dev-profile

You can use the region you want. I am using the eu-west-1 as I am based in Ireland. The default region is us-east-1.

The profile name is what you will pass to every --profile flag. Pick something short and descriptive — dev, personal, or work are all fine.

What gets written to your config file

The wizard creates two entries in ~/.aws/config (macOS/Linux) or %USERPROFILE%\.aws\config (Windows):

[sso-session my-dev-session]
sso_start_url = https://d-xxxxxxxxxx.awsapps.com/start
sso_region = eu-west-1
sso_registration_scopes = sso:account:access

[profile my-dev-profile]
sso_session = my-dev-session
sso_account_id = 123456789012
sso_role_name = PowerUserAccess
region = eu-west-1
output = json

Notice there are no access keys anywhere in this file. Credentials are fetched and cached at login time under ~/.aws/sso/cache/.

Step 4 — Log in and verify

aws sso login --profile my-dev-profile

Your browser opens, you approve the request, and the CLI caches a short-lived token locally. Then verify the profile is working:

aws sts get-caller-identity --profile my-dev-profile

Expected output:

{
    "UserId": "AROA...:user@example.com",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/PowerUserAccess/user@example.com"
}

If you see your account ID and role name, you are fully configured.

Step 5 — Set a default profile (optional but useful)

Passing --profile my-dev-profile to every command gets repetitive. Export it as an environment variable for your current session:

# macOS / Linux
export AWS_PROFILE=my-dev-profile

# Windows PowerShell
$env:AWS_PROFILE = "my-dev-profile"

To make it permanent, add the export line to your ~/.zshrc, ~/.bashrc, or PowerShell profile.

Now you can run commands without the flag:

aws s3 ls
aws sts get-caller-identity

Day-to-day workflow

Once everything is set up, your daily routine is just two commands:

# Start your working session
aws sso login --profile my-dev-profile

# When you are done
aws sso logout

Sessions expire automatically (typically after 8–12 hours, depending on your IAM Identity Center configuration). When credentials expire mid-session, the CLI will prompt you to re-run aws sso login.

Troubleshooting

aws: command not found after install
Restart your terminal. On macOS, run brew doctor to check your PATH. On Linux, confirm /usr/local/bin is in your $PATH.

Browser does not open on login
Run with the device code fallback:

aws sso login --profile my-dev-profile --use-device-code

The CLI will print a URL and a code — open the URL manually and enter the code.

Error when retrieving token from sso
Your cached token has expired. Re-run aws sso login --profile my-dev-profile.

AccessDenied on a command
Your permission set may not include the IAM action you are calling. Check the permissions attached to your IAM Identity Center permission set, or ask your AWS admin. The previous post in this series covers exactly how to map CLI commands to the IAM actions they require.

Key takeaways

AWS CLI v2 is required for aws configure sso (v1 will not work).
IAM Identity Center issues short-lived tokens. There are no long-lived keys stored on disk.
The sso-session block in ~/.aws/config handles token refresh automatically.
AWS_PROFILE environment variable saves you from typing --profile on every command.
aws sts get-caller-identity is your fastest way to confirm a profile is working.

Previous in this series: AWS IAM Demystified — Map Every S3 CLI Command to Its Exact Permission

AWS IAM + S3 Demystified: Map Every S3 CLI Command to Its Required Permission

BRUNO SOUZA — Fri, 13 Mar 2026 17:57:57 +0000

If you have ever stared at an AccessDenied error and played permission roulette, adding one action at a time until something works, this post is for you.

We are going to take a short, real S3 bash script, map every single CLI command to the exact IAM permission it requires, and write the smallest possible policy that grants only those actions.

What IAM is (in 60 seconds)

AWS IAM (Identity and Access Management) answers three questions for every API call:

Question	IAM concept
Who is calling?	Identity (user, role, or group)
What are they allowed to do?	Policy (JSON allow/deny rules)
On which resource?	Resource ARN

The evaluation logic is simple but strict:

Default deny — everything is blocked unless explicitly allowed
Explicit Allow — grants access
Explicit Deny — always wins, even over an Allow

That third rule is why least-privilege matters: the more permissions you hand out, the harder it is to audit which Deny you actually need.

The script we are dissecting

# create a bucket
aws s3api create-bucket --bucket hello-bucket --region eu-west-1 \
  --create-bucket-configuration LocationConstraint=eu-west-1

aws s3api put-bucket-acl --bucket hello-bucket --acl public-read

# upload a file to the bucket
aws s3 cp hello.txt s3://hello-bucket/hello.txt

# list the contents of the bucket
aws s3 ls s3://hello-bucket/

# delete the file from the bucket
aws s3 rm s3://hello-bucket/hello.txt

# download the file from the bucket
aws s3 cp s3://hello-bucket/hello.txt ./hello.txt

# delete the bucket
aws s3api delete-bucket --bucket hello-bucket

Seven commands. Seven IAM permission checks. Let us go through each one.

Command-to-permission map

#	Command	IAM action required
1	`aws s3api create-bucket`	`s3:CreateBucket`
2	`aws s3api put-bucket-acl`	`s3:PutBucketAcl`
3	`aws s3 cp` (upload)	`s3:PutObject`
4	`aws s3 ls`	`s3:ListBucket`
5	`aws s3 rm`	`s3:DeleteObject`
6	`aws s3 cp` (download)	`s3:GetObject`
7	`aws s3api delete-bucket`	`s3:DeleteBucket`

One thing most beginners miss: S3 permissions split across two resource levels.

Bucket-level actions (CreateBucket, ListBucket, PutBucketAcl, DeleteBucket) apply to arn:aws:s3:::bucket-name
Object-level actions (PutObject, GetObject, DeleteObject) apply to arn:aws:s3:::bucket-name/*

Getting this wrong is one of the most common sources of AccessDenied errors, even when the right action is listed.

The minimal IAM policy

Replace hello-bucket with your actual bucket name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BucketLevelAccess",
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:ListBucket",
        "s3:PutBucketAcl",
        "s3:DeleteBucket"
      ],
      "Resource": "arn:aws:s3:::hello-bucket"
    },
    {
      "Sid": "ObjectLevelAccess",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::hello-bucket/*"
    }
  ]
}

No wildcards. No s3:*. Just the seven actions the script actually calls.

Line-by-line walkthrough

1. Create a bucket

aws s3api create-bucket --bucket hello-bucket --region eu-west-1 \
  --create-bucket-configuration LocationConstraint=eu-west-1

IAM check: s3:CreateBucket on arn:aws:s3:::hello-bucket
The LocationConstraint is required for every region except us-east-1, which is the global default

2. Set a public ACL

aws s3api put-bucket-acl --bucket hello-bucket --acl public-read

IAM check: s3:PutBucketAcl
⚠️ 2026 note: AWS now enforces Object Ownership with ACLs disabled by default on new buckets. This command will throw AccessControlListNotSupported unless you explicitly set Object Ownership to BucketOwnerPreferred or ObjectWriter. For demos, skip the ACL step entirely and use bucket policies if you need public access.
Public ACLs are also blocked by Block Public Access settings at the account level — double-check yours.

3. Upload an object

aws s3 cp hello.txt s3://hello-bucket/hello.txt

IAM check: s3:PutObject on arn:aws:s3:::hello-bucket/*
Make sure the local file exists before running the script

4. List objects

aws s3 ls s3://hello-bucket/

IAM check: s3:ListBucket on arn:aws:s3:::hello-bucket
Note the resource is the bucket, not the objects — a common policy mistake

5. Delete an object

aws s3 rm s3://hello-bucket/hello.txt

IAM check: s3:DeleteObject on arn:aws:s3:::hello-bucket/*

6. Download an object

aws s3 cp s3://hello-bucket/hello.txt ./hello.txt

IAM check: s3:GetObject on arn:aws:s3:::hello-bucket/*

7. Delete the bucket

aws s3api delete-bucket --bucket hello-bucket

IAM check: s3:DeleteBucket on arn:aws:s3:::hello-bucket
The bucket must be empty before this succeeds. S3 will return a BucketNotEmpty error otherwise.

A production-ready version of the script

The original script has a few rough edges worth smoothing out before using it in a real environment. The corrected version below uses a timestamp suffix to avoid S3's global naming conflicts, ensures the file is downloaded before it is deleted, and removes the ACL step that fails by default on modern AWS accounts.

#!/usr/bin/env bash
set -euo pipefail

BUCKET="hello-bucket-$(date +%s)"
REGION="eu-west-1"
LOCAL_FILE="test.txt"
OBJECT_KEY="hello.txt"

# 1. Create bucket
aws s3api create-bucket \
  --bucket "$BUCKET" \
  --region "$REGION" \
  --create-bucket-configuration "LocationConstraint=$REGION"

# 2. Upload file
aws s3 cp "$LOCAL_FILE" "s3://$BUCKET/$OBJECT_KEY"

# 3. List objects
aws s3 ls "s3://$BUCKET/"

# 4. Download file (before deleting it)
aws s3 cp "s3://$BUCKET/$OBJECT_KEY" "./downloaded-$OBJECT_KEY"

# 5. Remove the object, then the bucket
aws s3 rm "s3://$BUCKET/$OBJECT_KEY"
aws s3api delete-bucket --bucket "$BUCKET"

The mental model I use before every AWS CLI command

Before writing or running any AWS CLI call, I ask three questions:

Which exact API action is this command calling?

Is the permission needed at the bucket level, object level, or both?

What is the narrowest resource ARN I can use?

That habit is what keeps IAM policies auditable. The moment you write s3:* or use "Resource": "*", you lose the ability to reason about what the policy actually permits.

Key takeaways

Every AWS CLI command maps to at least one IAM action — knowing the mapping is the core skill
S3 permissions split across two resource ARN patterns: bucket (:::name) and objects (:::name/*)
Modern AWS accounts disable ACLs by default — do not rely on put-bucket-acl in new scripts
Least privilege is not just a best practice; it is the only way to write policies you can actually audit

Mocking HTTP Services in PHP with Phiremock

BRUNO SOUZA — Tue, 03 Mar 2026 18:57:49 +0000

This article is part of a series on mock servers for backend developers. Part 1 covers language-agnostic tools (Postman, WireMock, and Pact Stub Server). This article focuses on Phiremock, the first of three PHP-specific tools covered in the series.

When your PHP application integrates with third-party APIs — payment gateways, logistics providers, marketplaces — testing those integrations reliably is a real challenge. Hitting real sandboxes is slow, fragile, and sometimes billable. Phiremock solves this by running a real HTTP server that your application calls instead, returning whatever response you define.

What is Phiremock?

Phiremock is a standalone HTTP mock server written in PHP, heavily inspired by WireMock. You run it as a separate process (or Docker container) and configure it via JSON expectation files or programmatically through its PHP client.

Current version: v1.5.1 (released December 2024)
PHP compatibility: ^7.2 | ^8.0
GitHub: https://github.com/mcustiel/phiremock

The key advantage over in-process mocking libraries is that Phiremock runs as a real HTTP server. Your application doesn't know it's talking to a mock; it makes real HTTP calls, making the tests more realistic.

Installation

Since version 2, Phiremock is split into two packages: the server and the client. Install both as dev dependencies:

composer require --dev mcustiel/phiremock-server mcustiel/phiremock-client

If you also need Guzzle as the HTTP client (default):

composer require --dev mcustiel/phiremock-server mcustiel/phiremock-client guzzlehttp/guzzle:^6.0

Starting the Server

Start Phiremock from the command line after installing:

vendor/bin/phiremock

By default, it listens on 0.0.0.0:8086. To customise:

vendor/bin/phiremock --port 8089 --ip 127.0.0.1 --debug

Configuration File

For a consistent setup, create a .phiremock file at your project root:

<?php 
  return [
      'port'             => 8089,
      'ip'               => '0.0.0.0',
      'expectations-dir' => './tests/expectations',
      'debug'            => false,
  ];

Phiremock searches for this file automatically at startup. Command-line arguments take priority over the config file.

Docker Compose

For a shared dev/CI environment, run Phiremock alongside your application:

services:
  app:
    build: .
    environment:
      PAYMENT_API_URL: http://phiremock:8086
    depends_on:
      - phiremock

  phiremock:
    image: mcustiel/phiremock
    ports:
      - "8086:8086"
    volumes:
      - ./tests/expectations:/var/www/phiremock/expectations

Once running, update your application config to point to http://localhost:8086 (or the Docker service name) instead of the real service URL.

Defining Expectations

An expectation tells Phiremock: "When you receive this request, return this response". You can define expectations in two ways: as JSON files loaded on startup, or programmatically via the PHP client at runtime.

JSON Expectations (Declarative)

Place JSON files in your expectations-dir directory. They are loaded automatically when Phiremock starts.
Match a GET request and return a product:

{
  "version": "2",
  "on": {
    "method": { "isSameString": "GET" },
    "url": { "isEqualTo": "/api/products/1" }
  },
  "then": {
    "response": {
      "statusCode": 200,
      "body": "{\"id\": 1, \"name\": \"Gift Box\", \"price\": 49.99}",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

Match a POST with a URL regex and simulate a 100ms delay:

{
  "version": "2",
  "on": {
    "method": { "isSameString": "POST" },
    "url": { "matches": "~/api/orders/?~" }
  },
  "then": {
    "delayMillis": 100,
    "response": {
      "statusCode": 201,
      "body": "{\"orderId\": \"abc-123\", \"status\": \"processing\"}",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

Simulate a 503 service unavailable

{
  "version": "2",
  "on": {
    "method": { "isSameString": "GET" },
    "url": { "isEqualTo": "/api/inventory/check" }
  },
  "then": {
    "response": {
      "statusCode": 503,
      "body": "{\"error\": \"Service temporarily unavailable\"}",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

Programmatic Expectations (PHP Client)

For dynamic test scenarios, define expectations in code using the Phiremock client. This is particularly useful in PHPUnit tests where each test needs a different response.

Setting up the client:

<?php

use Mcustiel\Phiremock\Client\Connection\Host;
use Mcustiel\Phiremock\Client\Connection\Port;
use Mcustiel\Phiremock\Client\Factory;
use Mcustiel\Phiremock\Client\Phiremock;
use Mcustiel\Phiremock\Client\Utils\A;
use Mcustiel\Phiremock\Client\Utils\Is;
use Mcustiel\Phiremock\Client\Utils\Respond;

$client = Factory::createDefault()->createPhiremockClient(
    new Host('localhost'),
    new Port(8086)
);

Creating the expectation

$client->createExpectation(
    Phiremock::on(
        A::getRequest()->andUrl(Is::equalTo('/api/products/1'))
    )->then(
        Respond::withStatusCode(200)
            ->andBody('{"id": 1, "name": "Gift Box", "price": 49.99}')
            ->andHeader('Content-Type', 'application/json')
    )
);

Matching by body content:

$client->createExpectation(
    Phiremock::on(
        A::postRequest()
            ->andUrl(Is::equalTo('/api/orders'))
            ->andBody(Is::containing('"productId":1'))
    )->then(
        Respond::withStatusCode(201)
            ->andBody('{"orderId": "abc-123"}')
            ->andHeader('Content-Type', 'application/json')
    )
);

Matching by header:

$client->createExpectation(
    Phiremock::on(
        A::getRequest()
            ->andUrl(Is::equalTo('/api/products'))
            ->andHeader('Authorization', Is::matching('/^Bearer .+/'))
    )->then(
        Respond::withStatusCode(200)
            ->andBody('[{"id": 1, "name": "Gift Box"}]')
            ->andHeader('Content-Type', 'application/json')
    )
);

Using with PHPUnit

Here is a complete PHPUnit test class that resets Phiremock state between tests and uses programmatic expectations:

Defining a config to run before the tests:

<?php

namespace App\Tests;

use Mcustiel\Phiremock\Client\Connection\Host;
use Mcustiel\Phiremock\Client\Connection\Port;
use Mcustiel\Phiremock\Client\Factory;
use Mcustiel\Phiremock\Client\Phiremock;
use Mcustiel\Phiremock\Client\Utils\A;
use Mcustiel\Phiremock\Client\Utils\Is;
use Mcustiel\Phiremock\Client\Utils\Respond;
use PHPUnit\Framework\TestCase;

class ProductServiceTest extends TestCase
{
    private static Phiremock $phiremock;
    private ProductService $productService;

    public static function setUpBeforeClass(): void
    {
        self::$phiremock = Factory::createDefault()->createPhiremockClient(
            new Host('localhost'),
            new Port(8086)
        );
    }

Defining the set up for the tests:

    protected function setUp(): void
    {
        // Clear all expectations and request history before each test
        self::$phiremock->clearExpectations();
        self::$phiremock->resetRequestsLog();

        // Point your service at the mock server
        $this->productService = new ProductService('http://localhost:8086');
    }

Writing the functions to test:

[Positive Scenario]

    public function testFetchesProductSuccessfully(): void
    {
        self::$phiremock->createExpectation(
            Phiremock::on(
                A::getRequest()->andUrl(Is::equalTo('/api/products/1'))
            )->then(
                Respond::withStatusCode(200)
                    ->andBody('{"id": 1, "name": "Gift Box", "price": 49.99}')
                    ->andHeader('Content-Type', 'application/json')
            )
        );

        $product = $this->productService->find(1);

        $this->assertEquals('Gift Box', $product['name']);
        $this->assertEquals(49.99, $product['price']);
    }

[Negative Scenario]

    public function testHandles404Gracefully(): void
    {
        self::$phiremock->createExpectation(
            Phiremock::on(
                A::getRequest()->andUrl(Is::equalTo('/api/products/999'))
            )->then(
                Respond::withStatusCode(404)
                    ->andBody('{"error": "Not found"}')
                    ->andHeader('Content-Type', 'application/json')
            )
        );

        $this->expectException(ProductNotFoundException::class);
        $this->productService->find(999);
    }

    public function testHandlesServiceTimeout(): void
    {
        self::$phiremock->createExpectation(
            Phiremock::on(
                A::getRequest()->andUrl(Is::equalTo('/api/products/1'))
            )->then(
                Respond::withStatusCode(200)
                    ->andBody('{"id": 1, "name": "Gift Box"}')
                    ->andDelayInMillis(3000) // simulate a slow response
            )
        );

        $this->expectException(ServiceTimeoutException::class);
        $this->productService->find(1);
    }

Verifying Calls

One of Phiremock's most useful features for strict test assertions is verifying that your application actually made the expected calls — not just that it returned the right result:

public function testCreatesOrderAndCallsPaymentGateway(): void
{
    self::$phiremock->createExpectation(
        Phiremock::on(
            A::postRequest()->andUrl(Is::equalTo('/api/payments/charge'))
        )->then(
            Respond::withStatusCode(200)
                ->andBody('{"chargeId": "ch_abc123", "status": "succeeded"}')
        )
    );

    $this->orderService->create(['productId' => 1, 'quantity' => 2]);

    // Assert the payment endpoint was called exactly once
    $executions = self::$phiremock->countExecutions(
        A::postRequest()->andUrl(Is::equalTo('/api/payments/charge'))
    );
    $this->assertEquals(1, $executions);
}

Stateful Scenarios

Phiremock supports scenarios (sequences of responses that transition state depending on how many times an endpoint has been called). This is useful for simulating async workflows, such as order processing or job polling.
Define two JSON expectations for the same endpoint with different scenario states:

First call — returns "processing":

{
  "version": "2",
  "scenarioName": "order-lifecycle",
  "on": {
    "scenarioStateIs": "Scenario.START",
    "method": { "isSameString": "GET" },
    "url": { "isEqualTo": "/api/orders/abc-123" }
  },
  "then": {
    "newScenarioState": "order-completed",
    "response": {
      "statusCode": 200,
      "body": "{\"orderId\": \"abc-123\", \"status\": \"processing\"}",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

Second call — returns "completed":

{
  "version": "2",
  "scenarioName": "order-lifecycle",
  "on": {
    "scenarioStateIs": "order-completed",
    "method": { "isSameString": "GET" },
    "url": { "isEqualTo": "/api/orders/abc-123" }
  },
  "then": {
    "response": {
      "statusCode": 200,
      "body": "{\"orderId\": \"abc-123\", \"status\": \"completed\"}",
      "headers": { "Content-Type": "application/json" }
    }
  }
}

The first time your application calls GET /api/orders/abc-123, it receives a processing status. The second call returns completed — no code changes needed between calls.
You can reset all scenarios to their initial state between tests via the client:

self::$phiremock->resetScenarios();

Pros & Cons

Pros:

Supports PHP 8, actively maintained (v1.5.1, December 2024)
Runs as a real HTTP server — tests are realistic end-to-end
Rich matching API: method, URL, body, headers, regex, exact match
Network latency simulation with delayMillis
Stateful scenarios for async workflows
Verify call counts for strict assertion
Docker image available for shared environments
Works with any PHP HTTP client

Cons:

Requires a running server process — adds infrastructure overhead
No built-in GUI (unlike Postman or WireMock)
The client requires Guzzle v6 by default (an older version)
More setup than in-process libraries for simple unit tests

When to Use Phiremock

Phiremock is the right choice when you need a mock server that multiple test suites, developers, or services can share, especially in a Docker Compose environment. If you need stateful scenarios, call verification, or realistic end-to-end HTTP testing where your app makes actual network connections to a real server, Phiremock is the strongest PHP-native option available.
For simpler, inline mocks that live entirely inside a single PHPUnit test class, take a look at the next tools in this series.

This article is part of a series on mock servers. Read Part 1: Language-Agnostic Tools (Postman, WireMock, Pact Stub Server), or continue with the next PHP tool in the series.

If you have questions or want to share how your team uses Phiremock, drop a comment below!

— Bruno Souza | Senior Software Engineer | LinkedIn

To Mock or Not to Mock: A Practical Guide to Mock Servers For APIs

BRUNO SOUZA — Wed, 25 Feb 2026 10:00:00 +0000

When you're building a backend that integrates with multiple third-party services, such as marketplaces, payment gateways, shipping providers, and 3PLs, your test suite quickly becomes a hostage to availability, rate limits, and unpredictable responses. I hit this problem hard while working on an integration platform that connected to external partners.

In this article, I'll walk through what mock testing is, why it matters, and give a practical overview of three language-agnostic tools: Postman Mock Server, WireMock, and the Pact Stub Server.

This is the first article in a three-part series:

Part 1 (this article): Language-agnostic tools — Postman, WireMock, and Pact Stub Server
Part 2: PHP-specific tools — Phiremock, HTTP Mock, and Mock Webserver
Part 3: Node.js-specific tools — Nock and MSW

The tools in this article don't care what language your application is written in. Whether you're running PHP, Node.js, Java, Python, or Go — these tools will work because they operate at the HTTP level, not at the code level. They're also the best choice when multiple services in different languages all need to share the same set of mocks.

What is Mock Testing?

Mock testing is the practice of emulating external services so your application can be tested against any scenario in complete isolation, without touching the real service.

The key advantages are that developers and testers get expected results without depending on a real (possibly unstable) external service, there's no risk of polluting production or staging data on third-party systems, you have full control over responses to simulate timeouts, 500 errors, malformed payloads, and edge cases, and tests run faster with no real network overhead.

The goal, in practical terms, is to intercept every outbound HTTP call your application makes and return a pre-defined, predictable response. Your code doesn't know the difference, and that's exactly the point.

Tools at a Glance

Tool	Type	How it runs	Best for
Postman Mock Server	Cloud-based GUI	Cloud (no setup)	Prototyping, team sharing, frontend collaboration
WireMock	HTTP stub server	Docker / standalone JAR	Powerful integration test environments
Pact Stub Server	HTTP stub server	Binary / Docker	Serving pre-written pact JSON files as a live mock

Postman Mock Server

If your team already uses Postman for API documentation and manual testing, spinning up a mock server from an existing collection is remarkably quick — and since it runs in the cloud, any service in any language can call it.

How to Create One

Step 1 — Add an example to a request.
Open a request inside a Collection, send it once to capture a real response, click the ... menu to the right of the request, and choose Add Example. Postman pre-fills it with the actual response you received.

Step 2 — Create the mock server.
Go to the Collection settings and click + New next to the Mock Servers section. Set the mock server name, pick an environment (e.g. API_LOCAL), optionally check Save the mock server URL as an environment variable, and click Create Mock Server.

Postman generates a unique URL like https://xxxxxxxx.mock.pstmn.io. Any request matching your saved examples will return the mocked response. In your application config, swap the base URL to point to the testing URL. No code changes needed.

Simulating Different Scenarios

You can add multiple examples to the same request, each with a different response body or status code. Postman selects the matching example based on query params, headers, or path.

For example, having two examples for GET /api/products/:id — one returning 200 with a product, another returning 404 with an error — lets different consumers test both paths just by hitting different URLs or passing different headers.

Pros & Cons

Pros: Zero configuration code, excellent GUI, language-independent (any service can call it), great for sharing mocks across teams, free tier available.

Cons: Responses must be captured from a real endpoint first — you can't fabricate a response that doesn't yet exist without manually editing the example body. Limited dynamic manipulation compared to code-based tools. Requires a Postman account.

WireMock

WireMock is the battle-tested standalone HTTP mock server originally from the Java ecosystem — but it's fully language-agnostic and works perfectly from any project. You run it as a Docker container or a standalone JAR, and interact with it via a REST API or one of its official client libraries for Node.js, Python, Go, and others.

It's the right choice when you need a powerful, long-lived mock server shared across multiple services in a Docker Compose environment, or when you need advanced features like stateful scenarios and response templating.

Starting WireMock via Docker

docker run -d \
  --name wiremock \
  -p 8080:8080 \
  -v $PWD/wiremock:/home/wiremock \
  wiremock/wiremock:latest

Once running, WireMock exposes http://localhost:8080 for your application to call, and http://localhost:8080/__admin for its management API.

Defining Stubs via the REST API

You can create stubs with a plain HTTP POST — any language, any tool:

curl -X POST http://localhost:8080/__admin/mappings \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "method": "GET",
      "url": "/api/products/1"
    },
    "response": {
      "status": 200,
      "body": "{\"id\": 1, \"name\": \"Gift Box\", \"price\": 49.99}",
      "headers": { "Content-Type": "application/json" }
    }
  }'

Stub Files (Declarative Approach)

Alternatively, drop JSON files into ./wiremock/mappings/ and they are loaded on startup — great for version-controlling your mock definitions alongside your code:

{
  "request": {
    "method": "POST",
    "urlPattern": "/api/orders",
    "bodyPatterns": [
      {
        "matchesJsonPath": "$.productId"
      }
    ],
    "headers": {
      "Authorization": { "matches": "Bearer .+" }
    }
  },
  "response": {
    "status": 201,
    "jsonBody": { "orderId": "abc-123" },
    "headers": { "Content-Type": "application/json" },
    "fixedDelayMilliseconds": 200
  }
}

Stateful Scenarios

One of WireMock's most powerful features is scenarios — mocks that change state based on how many times they've been called. This is perfect for simulating async workflows.

{
  "scenarioName": "Order Processing",
  "requiredScenarioState": "Started",
  "newScenarioState": "Processing",
  "request": {
    "method": "POST",
    "url": "/api/orders"
  },
  "response": {
    "status": 202,
    "jsonBody": { "status": "processing" }
  }
}

{
  "scenarioName": "Order Processing",
  "requiredScenarioState": "Processing",
  "request": {
    "method": "GET",
    "url": "/api/orders/abc-123"
  },
  "response": {
    "status": 200,
    "jsonBody": { "status": "completed" }
  }
}

Response Templating

WireMock can also extract data from the request and inject it into the response — useful when your code echoes back submitted data:

{
  "request": {
    "method": "POST",
    "url": "/api/products"
  },
  "response": {
    "status": 201,
    "body": "{\"id\": \"{{randomValue type='UUID'}}\", \"name\": \"{{{jsonPath request.body '$.name'}}}\"}",
    "headers": { "Content-Type": "application/json" },
    "transformers": ["response-template"]
  }
}

Pros & Cons

Pros: Extremely feature-rich (stateful scenarios, response templating, fault simulation, proxying); runs in Docker so it's shareable across a whole team or CI environment; battle-tested at enterprise scale; excellent documentation.

Cons: Requires a running Docker container or a Java process — more infrastructure overhead than in-process solutions; initial learning curve with the mapping DSL; the stub format is verbose for simple cases.

Pact Stub Server

The Pact Stub Server is a standalone HTTP mock server that serves responses defined in pact-format JSON files. You write your interactions (request/response pairs) as JSON, point the stub server at them, and it starts serving those responses immediately — no code required, no language SDK to install.

It's built in Rust, distributed as a single binary or a Docker image, and fully language-agnostic. The stub server is conceptually similar to WireMock's declarative mapping files, but uses the Pact V4 specification JSON format instead.

Note: This is not the same as Pact contract testing. The stub server simply serves pre-written responses — there is no consumer/provider verification involved. Contract testing is a separate topic we'll cover in a future article.

Installation

Via Docker (recommended):

docker pull pactfoundation/pact-stub-server

Via binary download:

Download the latest release for your platform from the GitHub releases page (supports Linux, macOS, and Windows on both x86_64 and arm64).

Writing a Pact Stub File

The stub server reads standard pact JSON files. You can write these by hand — they're just JSON files describing which request should return which response:

{
  "consumer": { "name": "ProductService" },
  "provider": { "name": "ProductAPI" },
  "interactions": [
    {
      "description": "get product 1",
      "request": {
        "method": "GET",
        "path": "/api/products/1"
      },
      "response": {
        "status": 200,
        "headers": { "Content-Type": "application/json" },
        "body": {
          "id": 1,
          "name": "Gift Box",
          "price": 49.99
        }
      }
    },
    {
      "description": "get unknown product",
      "request": {
        "method": "GET",
        "path": "/api/products/999"
      },
      "response": {
        "status": 404,
        "headers": { "Content-Type": "application/json" },
        "body": { "error": "Not found" }
      }
    },
    {
      "description": "create an order",
      "request": {
        "method": "POST",
        "path": "/api/orders",
        "headers": { "Content-Type": "application/json" }
      },
      "response": {
        "status": 201,
        "headers": { "Content-Type": "application/json" },
        "body": { "orderId": "abc-123", "status": "processing" }
      }
    }
  ]
}

Save this as pacts/ProductService-ProductAPI.json.

Running the Stub Server

From a single pact file:

pact-stub-server --file pacts/ProductService-ProductAPI.json --port 8080

From an entire directory of pact files:

pact-stub-server --dir pacts/ --port 8080

Via Docker, mounting a local pacts folder:

docker run -t -p 8080:8080 \
  -v "$(pwd)/pacts:/app/pacts" \
  pactfoundation/pact-stub-server \
  -p 8080 -d /app/pacts

Once running, your application points to http://localhost:8080 instead of the real service. The stub server matches incoming requests by method, path, and query parameters, then returns the matching response body and headers.

Docker Compose Integration

For a shared dev/test environment, add the stub server alongside your application services:

services:
  app:
    build: .
    environment:
      PRODUCT_API_URL: http://stub:8080
    depends_on:
      - stub

  stub:
    image: pactfoundation/pact-stub-server
    ports:
      - "8080:8080"
    volumes:
      - ./pacts:/app/pacts
    command: ["-p", "8080", "-d", "/app/pacts"]

Serving Multiple Scenarios with Provider States

If your application needs the same endpoint to return different responses depending on the test scenario (e.g. an existing product vs. an out-of-stock one), use provider states. Each interaction can declare a providerState, and you filter which state the stub server uses at runtime.

Add multiple interactions for the same endpoint with different provider states in your pact file:

{
  "consumer": { "name": "ProductService" },
  "provider": { "name": "ProductAPI" },
  "interactions": [
    {
      "description": "get product 1 - in stock",
      "providerState": "product 1 is in stock",
      "request": { "method": "GET", "path": "/api/products/1" },
      "response": {
        "status": 200,
        "body": { "id": 1, "name": "Gift Box", "available": true }
      }
    },
    {
      "description": "get product 1 - out of stock",
      "providerState": "product 1 is out of stock",
      "request": { "method": "GET", "path": "/api/products/1" },
      "response": {
        "status": 200,
        "body": { "id": 1, "name": "Gift Box", "available": false }
      }
    }
  ]
}

Start the stub server filtered to a specific state:

pact-stub-server --dir pacts/ --port 8080 --provider-state "in stock"

Or, if you need the server to handle multiple states in a single run, pass the desired state as a request header. Start the server with --provider-state-header-name:

pact-stub-server --dir pacts/ --port 8080 \
  --provider-state-header-name "X-Provider-State"

Then your test sends the header to tell the stub which interaction to match:

# Returns the "in stock" response
curl -H "X-Provider-State: product 1 is in stock" http://localhost:8080/api/products/1

# Returns the "out of stock" response
curl -H "X-Provider-State: product 1 is out of stock" http://localhost:8080/api/products/1

Watch Mode

During development, pact files change frequently. The --watch flag tells the stub server to monitor files and reload automatically without a restart:

pact-stub-server --dir pacts/ --port 8080 --watch

Any time you add, edit, or delete a pact file in the watched directory, the stub server picks up the changes immediately.

Loading Pacts from a URL or Pact Broker

The stub server can also fetch pact files from remote sources, which is useful in CI environments:

# Load from a URL
pact-stub-server --url https://your-server/pacts/ProductService-ProductAPI.json --port 8080

# Load from a Pact Broker (authenticated)
pact-stub-server \
  --broker-url https://your-pact-broker \
  --token your-bearer-token \
  --provider-name ProductAPI \
  --port 8080

CORS Support

For browser-based consumers (e.g. a React app calling the stub during development), enable CORS with the -o flag:

pact-stub-server --dir pacts/ --port 8080 --cors

This automatically responds to OPTIONS preflight requests and adds the Access-Control-Allow-Origin: * header to all responses.

Pros & Cons

Pros: Single binary with zero runtime dependencies — no JVM, no Node.js, no PHP needed; language-agnostic (any service can call it); JSON stub files are plain text and version-control friendly; watch mode makes development smooth; can pull pacts directly from a Pact Broker in CI; multi-platform Docker image available.

Cons: Matching is limited to method, path, and query params — no body-matching or conditional response logic like WireMock offers; response templating (injecting request data into responses) is not supported; designed primarily for prototyping rather than complex integration test scenarios.

Summary

The three tools in this article sit at different points on the effort/power spectrum. Postman gets you a shareable mock in minutes with no code, making it ideal for early prototyping and frontend collaboration. WireMock gives you the full power of a production-grade stub server with stateful scenarios and response templating, making it the right choice for complex integration test environments. The Pact Stub Server sits between the two — a single binary driven entirely by plain JSON files, with no infrastructure overhead and zero language dependencies.

In practice, they're not mutually exclusive: Postman works great during early development when the API isn't stable yet, the Pact Stub Server is a lightweight option for dev and CI environments where you want file-based stub definitions, and WireMock handles scenarios that need more sophisticated matching or stateful behaviour.

This is Part 1 of a three-part series on mock servers. Continue with Part 2: PHP Tools and Part 3: Node.js Tools. (To be published soon)

Article based on an internal presentation I gave at a previous company. If you have questions or want to share how your team approaches this problem, drop a comment below!

— Bruno Souza | Senior Software Engineer | LinkedIn

DEV Community: BRUNO SOUZA

The Autism Stats In The Tech Industry And The Real Hiring Problem

The numbers that fall apart

The numbers that survive

What to change in the loop

The Irish and EU angle nobody puts on the slide

The part senior engineers get wrong

The Singularity Is Nearer: What Ray Kurzweil's Six Epochs Gets Right About Our Future

The Law of Accelerating Returns (Quick Intro)

Epoch 1 — Physics and Chemistry

Epoch 2 — Biology and DNA

Epoch 3 — Brains

Epoch 4 — Technology

Epoch 5 — The Merger of Human and Machine Intelligence

Epoch 6 — The Universe Wakes Up

Why This Framework Matters to Engineers

How to Install the AWS CLI and Configure It with IAM Identity Center (SSO)

Why IAM Identity Center instead of aws configure?

Step 1 — Install AWS CLI v2

macOS

Linux (x86_64)

Windows

Verify the installation

Step 2 — Gather your IAM Identity Center details

Step 3 — Configure a profile with aws configure sso

What gets written to your config file

Step 4 — Log in and verify

Step 5 — Set a default profile (optional but useful)

Day-to-day workflow

Troubleshooting

Key takeaways

AWS IAM + S3 Demystified: Map Every S3 CLI Command to Its Required Permission

What IAM is (in 60 seconds)

The script we are dissecting

Command-to-permission map

The minimal IAM policy

Line-by-line walkthrough

1. Create a bucket

2. Set a public ACL

3. Upload an object

4. List objects

5. Delete an object

6. Download an object

7. Delete the bucket

A production-ready version of the script

The mental model I use before every AWS CLI command

Key takeaways

Mocking HTTP Services in PHP with Phiremock

To Mock or Not to Mock: A Practical Guide to Mock Servers For APIs

What is Mock Testing?

Tools at a Glance

Postman Mock Server

How to Create One

Simulating Different Scenarios

Pros & Cons

WireMock

Starting WireMock via Docker

Defining Stubs via the REST API

Stub Files (Declarative Approach)

Stateful Scenarios

Response Templating

Pros & Cons

Pact Stub Server

Installation

Writing a Pact Stub File

Running the Stub Server

Docker Compose Integration

Serving Multiple Scenarios with Provider States

Watch Mode

Loading Pacts from a URL or Pact Broker

CORS Support

Pros & Cons

Summary

Why IAM Identity Center instead of `aws configure`?

Step 3 — Configure a profile with `aws configure sso`