Introduction

This portfolio started as an Apple-style UI experiment. Then it became an actual application: a blog with a block editor, a diary, a chess repertoire, a contact form with Cloudflare Turnstile, photo uploads, and a Web3 page that reads my MetaMask balance.

The app kept growing. My testing strategy did not. I would run yarn dev, click the pages I remembered touching, and ship it. Basically: manual testing and hope.

That works when the project is small. It does not work once you have auth, API routes, shared components, and third-party services. I didn't need more random tests. I needed layers, each answering a different question, and a way to run them without relying on memory.

So I stopped adding features for a week and built that.

The architecture

Four layers:

Unit — does this function do what I think?
Contracts — does the API return the shape the frontend expects?
Integration — do hooks and components behave when HTTP fails, retries, or comes back partial?
E2E — can a real browser complete the flows that matter?

Most of the suite is cheap. At the time of writing: 378 unit/integration tests (~18s) and 24 Playwright tests (~20s). If every test were a browser test, I would stop running them. A suite you don't run is useless.

Stack: Vitest, React Testing Library, MSW, Zod, Playwright. Vitest fits Next 16 + ESM. Testing Library asserts what the user sees, not class names. MSW intercepts fetch so hooks run the real path. Zod was already in the project for forms, so I reused it for API shapes. Playwright is only the top layer.

One command is the bar:

{
  "validate": "yarn format:check && yarn lint && yarn typecheck && yarn test && yarn test:func && yarn build"
}

That answers: is this in a state I'm comfortable pushing? I like that better than relying on my memory.

Step 1: Pull logic out of the UI

Formatting, parsing, and validation kept ending up inside components. To test one rule I had to render the whole tree. I moved that into src/lib.

Wallet display is a good example. Zero, dust, trailing zeros, and invalid numbers are product decisions, not CSS:

const MIN_DISPLAYED_ETH = 0.00001

export const formatEthBalance = (eth: number) => {
  if (!Number.isFinite(eth) || eth <= 0) return '0'
  if (eth < MIN_DISPLAYED_ETH) return '<0.00001'
  return eth.toFixed(5).replace(/0+$/, '').replace(/\.$/, '')
}

A test named marks a dust balance as smaller than we can show is the requirement. Six months from now I won't remember why <0.00001 exists. The test will.

This layer didn't just verify behavior. It made unclear behavior visible — values that looked fine in the UI were lying once you defined what "zero" actually means.

Step 2: One Zod schema per API

The backend returns a shape. The frontend expects a shape. TypeScript tells you what you think it is. None of that checks what actually arrived.

export const ethBalanceResponseSchema = z.object({
  address: ethAddressSchema,
  wei: z.string(),
  eth: z.number()
})

Same schema in the route test, the client safeParse, the MSW fixtures, and the inferred type. A TypeScript interface will not catch an HTTP 200 whose body is an error string.

I also have a test that walks src/app/api and fails if a new route has no fixture. That one tests the process, not the app. Those are underrated.

This is where a retired third-party API showed up: the request succeeded, the body was not usable, and the UI had been treating that as a zero balance. The contract made the difference between "the request completed" and "the data is usable."

Step 3: MSW for the states you don't click into

Unit tests don't tell you what happens when one request succeeds and another fails, or when SWR retries. MSW lets the hook call fetch for real.

The product rule I locked in: if ETH loaded but USD didn't, show ETH. Do not invent $0.00. That means empty, not "price unknown."

SWR also retries failed requests and turns isLoading back on. During an outage the panel did this:

ETH → spinner → ETH → spinner

for as long as the endpoint was down. The fix is to treat a request that already failed as settled, and not replace useful data with a spinner on every retry. I wrote the test first. It failed with expected [ true, false ] to not include true. I would not have found that by opening the page.

Step 4: Keep Playwright thin

I don't want a browser test for every helper. I want it for paths where the pieces can all be green and the app is still broken: boot, public pages, auth redirects, contact validation, a couple of public APIs.

Two environment problems, not application bugs:

Playwright could inherit the deployed app URL. Contact tests submit forms. Default is localhost now. Pointing at production is an explicit opt-in.
Turnstile's visible test key waits for a click that headless Chrome never makes. Use the non-interactive test key.

E2E is there to prove the pieces are connected, not to redo Vitest in Chromium.

Step 5: Put the gate in a hook

Tests you have to remember to run are tests you eventually stop running.

Pre-commit: format, lint, types, unit tests (fast, I commit often).
Pre-push: yarn validate, including Playwright and next build.
Commit messages: Conventional Commits. fix(web3): handle balance API errors is in. fixed stuff is out. I don't want to argue with myself about that in six months.

The gate had its own bug: lint-staged treated ESLint-ignored files as warnings, and --max-warnings=0 blocked the commit. The app was fine. The process wasn't. If automation nags you for no reason, you disable it — so the gate has to be trustworthy too.

What else showed up

I already covered the dead API, the fake zeros, and the SWR flicker above. Two more from the first real run:

News images. Some feed URLs aren't in the next/image allowlist. The page threw instead of falling back.
Line endings. One route file had Classic Mac \r. JS parsed it. Git showed the whole file as one line. The PR would have been unreadable. Lint, types, and the build all said it was fine.

That last one is why I care about workflow as much as runtime. The app wasn't broken. The review would have been.

Coverage is 31%, on purpose

I configured coverage with all: true across src, including pages I didn't try to cover this week. 31% is the honest repo number. The code this work touched is much higher.

I'm not chasing 100% for a README badge. I'd rather have tests on decisions and failure states than tests written to move a percentage. The 31% is useful because it shows the gaps. Coverage is a signal, not confidence.

If you're about to do this

Don't start with "I need 500 tests." Start with the questions the app actually has to answer, then pick the cheapest layer that can answer each one.

Pull formatting and validation out of components.
Validate API JSON at runtime, not just in TypeScript.
Test failures, partial data, and retries. The interesting bugs were not on the happy path.
Automate the gate. Don't leave it as a personal habit.
Test the decision (shows ETH when price is down), not the internals (calls useSWR twice).
Keep E2E small, and never let it default to production.

Conclusion

A week of work: 378 fast tests, 24 browser tests, hooks that run before I push.

What changed is not the count. Before this, the question was "I clicked around and it seemed okay." Now I can ask whether a function handles bad input, whether a response matches the contract, whether the UI keeps data it still has, whether a signed-out visitor hits a protected route, and whether those checks run every time.

The bugs afterward were not the goal. They were proof the layers were looking at different things — runtime, contracts, retries, the real browser, and the workflow around the code.

You don't need a huge setup on day one. Identify the kinds of questions your app needs to answer, then add the smallest layer that can answer each one. The bugs you find later are useful. The system that keeps finding them is the point.

How I Added a Layered Testing Architecture to This Portfolio

How I Added a Layered Testing Architecture to This Portfolio

Comments