RealWorld (Conduit) — Administrator & Developer Guide

1. Architecture Overview

RealWorld is not a deployable application — it is a specification repository that defines the "Conduit" blogging platform contract. The repository provides three core deliverables: an OpenAPI specification defining the REST API contract, a multi-runner test infrastructure for validating implementations, and an Astro-based documentation site publishing the specification for implementors.

The architecture follows a spec-first design: the OpenAPI document (specs/api/openapi.yml) is the single source of truth. Test suites in two formats (Hurl and Bruno) validate implementations against this contract. A Playwright E2E suite validates frontend implementations. All three layers reference the same behavioral expectations but target different audiences (backend devs, API explorers, and frontend devs respectively).

specs/api/openapi.yml          ← API contract (source of truth)
     │
     ├── specs/api/hurl/*.hurl ← Backend compliance tests (canonical)
     │       │
     │       └── specs/api/hurl-to-bruno.js  → specs/api/bruno/  (generated)
     │
     ├── specs/e2e/*.spec.ts   ← Frontend E2E tests (Playwright)
     │       │
     │       └── specs/e2e/helpers/  ← Shared test utilities
     │
     ├── docs/                 ← Specification documentation site (Astro/Starlight)
     │
     └── assets/               ← Shared media (logos, icons, theme CSS)

Component Inventory

Technology Stack

Note

The repository has no application runtime dependencies. All dependencies belong to either the documentation site (docs/package.json) or the tooling scripts. Implementations bring their own stack.

Data Flow: API Test Execution

1. User sets HOST=http://localhost:PORT
2. run-api-tests-hurl.sh generates unique uid (timestamp + PID)
3. Script discovers all *.hurl files, runs sequentially (--jobs 1)
4. Each .hurl file:
   a. Registers test user(s) with uid-based unique credentials
   b. Performs CRUD operations against the API
   c. Captures variables (tokens, slugs, comment IDs) via [Captures]
   d. Asserts response status codes and JSON body via [Asserts]
5. Exit code 0 = all passed, non-zero = failures

Data Flow: Hurl-to-Bruno Conversion

1. hurl-to-bruno.js reads all *.hurl files from specs/api/hurl/
2. parseHurlFile() extracts: method, URL, headers, JSON body,
   status code, captures, and jsonpath assertions
3. Each Hurl file becomes a Bruno folder (underscores → hyphens)
4. Each request within a file becomes a numbered .bru file
5. Hurl captures → bru.setVar() in script:post-response
6. Hurl jsonpath assertions → Chai expect() assertions
7. Collection-level pre-request generates unique uid variable
8. --check mode: generates to temp dir, diffs against existing

2. System Requirements

For Running API Tests

For Running E2E Tests

For Building the Documentation Site

Disk Space

The repository is 309 files / ~104K characters of source. The docs/ node_modules adds ~200MB. Mobile icon assets contribute the bulk of the file count (70+ PNG files across density buckets).

3. Configuration Reference

Environment Variables

Important

API_BASE defaults to the public demo server at https://api.realworld.show/api. For local development, always override this to avoid running tests against production.

Configuration Files

Playwright Base Configuration (Exact Values)

{
  testDir: './e2e',
  fullyParallel: false,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 1,
  workers: 1,
  reporter: 'html',
  timeout: 15_000,
  use: {
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    actionTimeout: 5_000,
    navigationTimeout: 10_000,
  },
  expect: { timeout: 5_000 },
  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
}

Warning

workers: 1 and fullyParallel: false are intentional constraints. Tests share backend state (created users, articles) and parallel execution causes flaky failures from resource exhaustion.

OpenAPI Specification: Endpoint Summary

OpenAPI Schema: Data Models

Authentication Scheme

The API uses a custom Token scheme (not Bearer):

Authorization: Token eyJhbGciOiJIUzI1NiIs...

Defined as apiKey type in the securitySchemes section, applied via the Authorization header. Tokens are JWTs returned by the registration and login endpoints.

Error Response Format

All errors use the GenericErrorModel envelope:

{
  "errors": {
    "field_name": ["error message 1", "error message 2"]
  }
}

Standard HTTP status codes:

• 401 Unauthorized — missing or invalid token
• 403 Forbidden — user lacks permission for the operation
• 404 Not Found — resource doesn't exist
• 409 Conflict — duplicate resource (username/email)
• 422 Unprocessable Entity — validation error

Pagination Parameters

Applied to GET /articles, GET /articles/feed.

Article Query Filters

4. Deployment & Scaling

Documentation Site Deployment

The documentation site builds to static files:

cd docs
npm run build

astro check && astro build

Output goes to docs/dist/. Deploy to any static hosting (Netlify, Vercel, GitHub Pages, S3/CloudFront).

Tip

The docs/README.md includes one-click deploy buttons for Netlify and Vercel using the Starlight template.

CI Integration

Add API compliance checks to your implementation's CI pipeline:

# GitHub Actions example
- name: Run RealWorld API compliance tests
  run: |
    HOST=http://localhost:3000 bash specs/api/run-api-tests-hurl.sh

For E2E tests in CI:

- name: Run E2E tests
  env:
    CI: true
    API_BASE: http://localhost:3000/api
  run: npx playwright test

Note

Setting CI=true enables forbidOnly: true (fails on test.only() left in code) and increases retries from 1 to 2.

Bruno Collection CI Check

- name: Verify Bruno collection in sync
  run: bun specs/api/hurl-to-bruno.js --check

5. Operations

Test Suite Maintenance

Adding New API Endpoints

1. Add the endpoint to specs/api/openapi.yml
2. Create or extend the appropriate specs/api/hurl/*.hurl test file
3. Regenerate Bruno: bun specs/api/hurl-to-bruno.js
4. Verify: bun specs/api/hurl-to-bruno.js --check

Adding New E2E Tests

1. Create or extend a specs/e2e/*.spec.ts file
2. Use existing helpers from specs/e2e/helpers/ for common operations
3. Follow the established pattern: test.beforeEach for user registration, test.afterEach for context cleanup with cooldown delay

Tip

The 500ms–1000ms cooldown in afterEach hooks prevents resource exhaustion when running 6+ sequential tests. Always include await context.close() followed by a delay.

Updating the Hurl-to-Bruno Converter

The converter at specs/api/hurl-to-bruno.js handles these Hurl assertion types:

Unsupported assertion types throw Error: Unhandled hurl assert.

Monitoring

There is no runtime application to monitor. The key operational concerns are:

• Test suite health: Run the full Hurl + E2E suite against the demo backend (https://api.realworld.show/api) periodically to catch spec regressions
• Bruno sync: Use --check mode in CI to prevent drift between Hurl sources and the Bruno collection
• Documentation site: The Astro build fails fast on TypeScript errors (astro check runs before astro build)

6. Performance

Test Execution Timing

The Hurl test suite runs sequentially (--jobs 1) because tests depend on state created by earlier tests within each file (e.g., register → login → create article → verify). There is no parallelism path for API tests.

Playwright E2E tests run with workers: 1 for the same reason. The afterEach cooldown delays (500ms–1000ms) add overhead but prevent flaky failures:

Note

The afterEach cooldown pattern is documented in source comments as a known workaround: "This timing issue manifests as timeouts when loading article pages. This will be investigated and fixed later."

Hurl-to-Bruno Converter Performance

The converter processes all 14 Hurl files in a single pass. In --check mode, it generates to a temp directory, compares file-by-file, and cleans up. The temp directory is always removed in a finally block.

7. Security

API Authentication Requirements

The specification defines security boundaries:

• Public endpoints (no auth): GET /articles, GET /articles/{slug}, GET /profiles/{username}, GET /tags, POST /users, POST /users/login
• Auth-required endpoints (Token header): All write operations (create, update, delete) and GET /user, GET /articles/feed
• Auth-optional endpoints: GET /articles (adds favorited context), GET /profiles/{username} (adds following flag)

The error test suites (errors_auth.hurl, errors_authorization.hurl) validate:

• Missing token returns 401 for protected endpoints
• Cross-user article update/delete returns 403
• Cross-user comment deletion returns 403
• Unknown resource access returns 404

XSS Security Test Coverage

The E2E suite includes smoke-level XSS security tests (xss-security.spec.ts) that inject malicious payloads directly via API (bypassing UI sanitization) to test frontend resilience:

Image URL injection payloads tested:

• onerror attribute injection
• onload attribute injection
• javascript: protocol in src
• data: URI with script content

Markdown body payloads tested:

• <script> tags
• <img onerror> tags
• <svg onload> tags
• <iframe srcdoc> tags
• <a href="javascript:"> links
• <div onmouseover> event handlers

Verification method: A dialog listener (page.on('dialog')) detects if any alert() fires, plus DOM checks for dangerous attributes (onerror, onload, onmouseover, onclick, onfocus) and injected <script> elements.

Caution

The XSS tests are explicitly documented as "BASIC SMOKE TESTS ONLY" — they are not a comprehensive security audit. The test file recommends professional security audits, OWASP ZAP/Burp Suite scanning, and CSP headers for production applications.

Frontend Error Handling Specification

The E2E suite defines expected frontend behavior for error conditions:

Warning

The user-fetch-errors.spec.ts tests explicitly validate that 5XX errors on /api/user preserve the JWT token in localStorage. Frontends that clear the token on server errors will fail these tests — the distinction between "your token is bad" (4XX) and "the server is down" (5XX) is enforced.

8. Developer Internals

Repository Structure

realworld/
├── README.md                           # Project overview
├── CONTRIBUTING.md                     # Contribution guidelines
├── LICENSE                             # MIT license
├── Makefile                            # Build automation
├── assets/
│   ├── media/
│   │   ├── conduit-logo.svg            # Generated logo
│   │   ├── conduit-logo.svg.generate.ts # Logo generator (Bun + OpenType.js)
│   │   ├── default-avatar.svg          # Default user avatar
│   │   ├── realworld-logo.{png,svg}    # RealWorld branding
│   │   ├── realworld-dual-mode.png     # Light/dark mode screenshot
│   │   └── mobile_icons/              # iOS, Android, watchOS, iMessage icons
│   └── theme/
│       └── styles.css                  # Shared Conduit CSS theme
├── docs/                               # Astro/Starlight documentation site
│   ├── package.json                    # Standalone deps (astro, starlight, react, tailwind)
│   ├── astro.config.mjs                # Site configuration
│   ├── tsconfig.json                   # TypeScript config (strict + React JSX)
│   ├── src/
│   │   ├── env.d.ts                    # Astro type declarations
│   │   ├── tailwind.css                # Tailwind entry point
│   │   ├── content/
│   │   │   ├── config.ts               # Astro content collection (docsSchema)
│   │   │   └── docs/                   # Specification content (md/mdx)
│   │   │       ├── index.mdx           # Landing page
│   │   │       ├── introduction.mdx
│   │   │       ├── specifications/     # Backend, frontend, mobile specs
│   │   │       ├── implementation-creation/ # How to build an impl
│   │   │       └── community/          # Authors, resources, thanks
│   │   └── assets/img/                 # Site images
│   └── public/
│       └── favicon.svg
├── specs/
│   ├── api/
│   │   ├── openapi.yml                 # OpenAPI 3.1 specification
│   │   ├── hurl-to-bruno.js            # Converter (Bun, 597 lines)
│   │   ├── run-api-tests-hurl.sh       # Hurl test runner
│   │   ├── run-api-tests-bruno.sh      # Bruno test runner
│   │   ├── hurl/                       # 14 Hurl test files
│   │   │   ├── auth.hurl
│   │   │   ├── articles.hurl
│   │   │   ├── comments.hurl
│   │   │   ├── favorites.hurl
│   │   │   ├── feed.hurl
│   │   │   ├── profiles.hurl
│   │   │   ├── tags.hurl
│   │   │   ├── pagination.hurl
│   │   │   ├── errors_auth.hurl
│   │   │   ├── errors_articles.hurl
│   │   │   ├── errors_authorization.hurl
│   │   │   ├── errors_comments.hurl
│   │   │   ├── errors_profiles.hurl
│   │   │   └── run-hurl-tests.sh       # Alternative runner (inside hurl dir)
│   │   └── bruno/                      # Generated Bruno collection
│   │       ├── bruno.json
│   │       ├── collection.bru
│   │       ├── environments/local.bru
│   │       ├── auth/                   # 20 test files
│   │       ├── articles/               # 17 test files
│   │       ├── comments/               # 13 test files
│   │       ├── favorites/              # 9 test files
│   │       ├── feed/                   # 12 test files
│   │       ├── profiles/               # 7 test files
│   │       ├── tags/                   # 4 test files
│   │       ├── pagination/             # 7 test files
│   │       ├── errors-auth/            # 15 test files
│   │       ├── errors-articles/        # 20 test files
│   │       ├── errors-authorization/   # 9 test files
│   │       ├── errors-comments/        # 10 test files
│   │       └── errors-profiles/        # 6 test files
│   └── e2e/
│       ├── playwright.base.ts          # Base Playwright config
│       ├── SELECTORS.md                # CSS selector documentation
│       ├── auth.spec.ts                # Authentication tests (8)
│       ├── articles.spec.ts            # Article CRUD tests (10)
│       ├── comments.spec.ts            # Comment tests (8)
│       ├── navigation.spec.ts          # Navigation/filtering tests (9)
│       ├── social.spec.ts              # Follow/profile tests (5)
│       ├── settings.spec.ts            # Settings form tests
│       ├── error-handling.spec.ts       # Error resilience tests (18)
│       ├── user-fetch-errors.spec.ts    # Init error tests (12)
│       ├── null-fields.spec.ts         # Nullable field tests (11)
│       ├── url-navigation.spec.ts      # URL routing tests (7)
│       ├── health.spec.ts              # Smoke tests (4)
│       ├── xss-security.spec.ts        # XSS smoke tests (12)
│       └── helpers/
│           ├── api.ts                  # Direct API helpers (register, login, create article, update user, bulk create)
│           ├── articles.ts             # UI article helpers (create, edit, delete, favorite, unfavorite, generate)
│           ├── auth.ts                 # UI auth helpers (register, login, logout, generateUniqueUser)
│           ├── comments.ts             # UI comment helpers (add, delete, count)
│           ├── config.ts               # Environment config (API_MODE, API_BASE)
│           ├── debug.ts                # Debug interface helpers (getToken, getAuthState, getCurrentUser)
│           ├── profile.ts              # UI profile helpers (follow, unfollow, updateProfile)
│           └── setup.ts                # Setup utilities (createUserInIsolation, createManyArticles)

Module Reference

specs/api/hurl-to-bruno.js (597 lines)

The core conversion tool. Written as a Bun executable (#!/usr/bin/env bun), it performs a full pipeline:

Parsing (parseHurlFile()): State machine with 6 states (IDLE, HEADERS, BODY, RESPONSE, ASSERTS, CAPTURES). Handles:

• Comment lines as request names
• HTTP methods (GET, POST, PUT, DELETE, PATCH)
• Header parsing (Key: Value)
• JSON body extraction with brace-depth tracking
• HTTP NNN status assertions
• [Asserts] section with jsonpath expressions
• [Captures] section for variable extraction

Transformation: Converts Hurl concepts to Bruno equivalents:

• slugify() — generates filesystem-safe names from comments
• jsonpathToJs() — $.user.token → res.body.user.token
• transformValue() — handles null, booleans, numbers, {{var}} templates, quoted strings with embedded variables
• assertToJs() — 14 assertion types mapped to Chai expect() chains

Generation (generateBruFile()): Produces .bru format sections:

• meta {} — name and sequence number
• METHOD {} — URL and body type
• headers {} — request headers
• body:json {} — indented JSON body (2-space indent to avoid parser ambiguity)
• assert {} — status code check
• script:post-response {} — variable captures + Chai assertions

Collection structure: generateCollection() creates:

• bruno.json — collection metadata
• collection.bru — pre-request script generating unique uid
• environments/local.bru — default host variable
• One folder per Hurl file, one .bru file per request

Check mode (checkMode()): Generates to temp directory, compares file-by-file (missing, extra, changed), exits non-zero on drift.

specs/e2e/helpers/config.ts (2 lines)

Resolves two environment variables:

• API_MODE: true unless process.env.API_MODE is explicitly "false" (case-insensitive)
• API_BASE: defaults to https://api.realworld.show/api

specs/e2e/helpers/api.ts (108 lines)

Direct API helpers for test setup, bypassing the UI for speed:

• registerUserViaAPI() — POST /users, returns JWT token
• loginUserViaAPI() — POST /users/login, returns JWT token
• createArticleViaAPI() — POST /articles, returns article slug
• updateUserViaAPI() — PUT /user
• createManyArticles() — bulk article creation with 100ms delays between requests

specs/e2e/helpers/auth.ts (53 lines)

UI-based authentication flows:

• register() — fills form at /register, waits for redirect to /
• login() — fills form at /login, waits for redirect to /
• logout() — navigates to /settings, clicks logout button
• generateUniqueUser() — returns { username, email, password } with Date.now() uniqueness

specs/e2e/helpers/articles.ts (93 lines)

UI-based article operations:

• createArticle() — fills editor form, waits for article page redirect
• editArticle() — navigates to /editor/{slug}, waits for form population, updates fields
• deleteArticle() — clicks delete button, waits for home redirect
• favoriteArticle() / unfavoriteArticle() — toggles favorite button state
• generateUniqueArticle() — returns article data with timestamp uniqueness

specs/e2e/helpers/comments.ts (33 lines)

UI-based comment operations:

• addComment() — fills comment textarea, clicks Post, waits for comment count to increase
• deleteComment() — finds comment card by text, clicks trash icon
• getCommentCount() — counts .card:not(.comment-form) .card-block elements

specs/e2e/helpers/debug.ts (67 lines)

Interface to window.__conduit_debug__:

• getToken() — retrieves JWT from debug interface
• getAuthState() — returns authenticated | unauthenticated | unavailable | loading
• getCurrentUser() — returns user object or null
• waitForAuthState() — polls until expected state is reached
• isDebugInterfaceAvailable() — checks if implementation exposes the interface

specs/e2e/helpers/profile.ts (60 lines)

UI-based profile operations:

• followUser() — navigates to /profile/{username}, clicks Follow, waits for Unfollow
• unfollowUser() — navigates to /profile/{username}, clicks Unfollow, waits for Follow
• updateProfile() — fills settings form, handles both API_MODE and form-only submissions

specs/e2e/helpers/setup.ts (46 lines)

High-level setup utilities:

• createUserInIsolation() — creates user in a separate browser context (for non-API mode)
• createManyArticles() — dispatches to API or form-based creation depending on API_MODE

assets/media/conduit-logo.svg.generate.ts (41 lines)

Bun script that:

1. Downloads Caudex Bold font from Google Fonts to .tmp/
2. Loads font with opentype.js
3. Renders "Conduit" text at 48px to SVG path data
4. Computes tight bounding box with 2px padding
5. Writes conduit-logo.svg with fill="#222"

Code Patterns and Conventions

State machine parsing: The Hurl parser uses a state machine pattern (IDLE → HEADERS → BODY → RESPONSE → ASSERTS → CAPTURES) rather than a grammar parser. This is brittle for complex Hurl features but sufficient for the jsonpath-centric test files in this repo.

Test isolation: Every E2E test creates its own user via generateUniqueUser() using Date.now() for uniqueness. Browser contexts are explicitly closed in afterEach with cooldown delays.

Dual-mode tests: E2E tests check API_MODE to determine whether to use direct API calls (faster) or form-based UI flows (more realistic). API-only tests are skipped with test.skip(!API_MODE, 'reason').

Variable capture chain: Hurl tests use [Captures] to extract values (tokens, slugs, comment IDs) that subsequent requests use via {{variable}} interpolation. The Bruno converter maps these to bru.setVar() / bru.getVar().

Pre-request UID generation: The Bruno collection-level script:pre-request generates a unique uid combining Date.now() with random characters, ensuring test isolation per collection run.

Testing Strategy

The repository has three test layers, each targeting different aspects:

API test coverage areas: Registration/login, article CRUD, comments, favorites, feeds, profiles, tags, pagination, error codes (400/401/403/404/409/422), authorization boundaries, nullable field normalization.

E2E test coverage areas: All API areas plus: session persistence, token invalidation recovery, XSS prevention, URL-based routing, default avatar rendering, null field display, network error resilience, HTTP status code flexibility (200 vs 204 for DELETE).

Known Issues from Community

Potential Improvements

• Parallel test execution: The sequential --jobs 1 constraint limits test speed. Implementing proper test isolation (unique databases per test run) would enable parallelism.
• Non-jsonpath assertions: The hurl-to-bruno converter only handles jsonpath assertions. Supporting header, cookie, and body assertions would enable full-fidelity conversion.
• Mobile specification: The docs/src/content/docs/specifications/mobile-specs/ directory exists with an introduction but the mobile spec content is incomplete.
• Automated E2E test discovery: Implementations currently must manually copy/symlink the specs/e2e/ directory. A package distribution model would simplify consumption.
• Dedicated CSS selector contract: specs/e2e/SELECTORS.md documents the CSS selectors the E2E tests depend on, but there's no automated enforcement that implementations use these exact selectors.

9. Integration Points

For Backend Implementations

Backend implementations must conform to:

1. OpenAPI spec at specs/api/openapi.yml — all 15 endpoints with exact request/response schemas
2. Authentication — JWT tokens with Token prefix in Authorization header
3. Error format — { "errors": { "field": ["message"] } } envelope
4. Nullable fields — bio and image accept null and normalize empty strings to null
5. CORS — enabled for frontend cross-origin requests (spec mentions CORS in docs)
6. Status codes — 201 for creation, 204 for deletion (200 also accepted by frontends), 4XX/5XX per spec

Validate with: HOST=http://your-server bash specs/api/run-api-tests-hurl.sh

For Frontend Implementations

Frontend implementations must:

1. Route structure — /, /login, /register, /editor, /editor/{slug}, /article/{slug}, /profile/{username}, /profile/{username}/favorites, /settings, /tag/{tag}, /?feed=following
2. CSS classes — .navbar, .banner, .article-preview, .article-content, .article-meta, .feed-toggle, .tag-list, .tag-pill, .tag-default, .user-info, .user-img, .user-pic, .comment-form, .comment-author-img, .error-messages, .sidebar, .pagination, .page-item, .empty-feed-message, .mod-options
3. Form elements — input[name="title"], input[name="description"], textarea[name="body"], input[placeholder="Enter tags"], input[name="email"], input[name="password"], input[name="username"], input[name="image"], textarea[name="bio"], textarea[placeholder="Write a comment..."]
4. Buttons — button:has-text("Publish Article"), button:has-text("Delete Article"), button:has-text("Follow"), button:has-text("Unfollow"), button:has-text("Favorite"), button:has-text("Unfavorite"), button:has-text("Post Comment"), button:has-text("Update Settings"), button:has-text("Or click here to logout")
5. Debug interface (optional) — window.__conduit_debug__ with getToken(), getAuthState(), getCurrentUser()
6. Default avatar — render default-avatar.svg when user image is null or empty
7. Error handling — 4XX clears token and shows logged-out UI; 5XX preserves token and shows "Connecting" state

Validate with: API_BASE=http://your-api npx playwright test --config specs/e2e/playwright.base.ts

For Documentation Contributors

The docs site uses Astro content collections:

// docs/src/content/config.ts
export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
};

Add new pages as .md or .mdx files in docs/src/content/docs/. Starlight automatically generates navigation from the file structure. Images go in docs/src/assets/img/.