Skip to content

CLAUDE.md

Latest commit

 

History

History
69 lines (50 loc) · 2.68 KB

CLAUDE.md

File metadata and controls

69 lines (50 loc) · 2.68 KB
Raw

CLAUDE.md

What this repo is

This is the RealWorld spec & docs hub — not an implementation. It defines the contract that every RealWorld frontend and backend adheres to, and hosts the test suites used to validate them. Nothing here is a runnable app.

  • specs/api/ — the API contract: openapi.yml plus the Hurl and Bruno test suites that a backend must pass.
  • specs/e2e/ — a shared Playwright suite that validates a frontend, plus SELECTORS.md (the selector contract) and playwright.base.ts.
  • docs/ — the Astro/Starlight site published at https://docs.realworld.show/.
  • Makefile — entry points (run make help).
  • CONTRIBUTING.md — the human contribution process.

If you are here as a submodule / vendored dependency

An implementation embeds this repo to test itself against the spec (the E2E suite is literally consumed as ./e2e). If that's why you're reading this:

  • Fix the implementation, never edit the spec or tests to make them pass. Files under specs/ are the source of truth a failing implementation must conform to.
  • Edit files here only when the task is explicitly about changing the RealWorld spec itself.

Conventions

  • Use bun, not npm/node, for everything in this repo.
  • Hurl is the source of truth for the API suite; the Bruno collection is generated from it. Don't hand-edit specs/api/bruno/ — change the Hurl files and regenerate.
  • Docs URLs are written with a trailing slash.

Running the test suites

API suite (point HOST at a running backend, run from specs/api/):

HOST=http://localhost:3000/api ./run-api-tests-hurl.sh    # source of truth
HOST=http://localhost:3000/api ./run-api-tests-bruno.sh    # generated mirror

Regenerate / verify the Bruno collection:

make bruno-generate    # rebuild specs/api/bruno/ from the Hurl files
make bruno-check       # CI check: fail if bruno/ is out of sync

E2E suite: an implementation extends specs/e2e/playwright.base.ts (override baseURL and webServer) and must satisfy specs/e2e/SELECTORS.md. See https://docs.realworld.show/specifications/frontend/tests/.

Working on the docs

make documentation-setup     # cd docs && bun install
make documentation-dev       # local dev server
make documentation-build     # production build

Answering "how do I build an implementation?"

Implementations live in their own repos, not here. Point users to: