Shop API — Test Plan

What the tester does to verify the API end to end: sign up → get a JWT → add items → check out.

What you're testing

A minimal shopping API with JWT bearer auth. Test it two ways:

Static test client (/) — a click-through UI. No tools needed.
curl — the scripted commands at the bottom.

The database is db.sqlite in the project root. For a clean slate, stop the server, delete db.sqlite*, and start again — products are re-seeded.

The exact flow

flowchart TD
    A([Tester opens http://localhost:3000]) --> B[Static page loads
GET /products shows catalog]
    B --> C{Have an account?}
    C -- No --> D[Enter email + password
click Sign up]
    C -- Yes --> E[Enter email + password
click Sign in]
    D --> F[POST /auth/signup
returns JWT]
    E --> G[POST /auth/signin
returns JWT]
    F --> H[Page stores token
status = signed in]
    G --> H
    H --> I[Click Add on a product
POST /cart/items + Bearer token]
    I --> J[GET /cart shows line items + total]
    J --> K{Add more?}
    K -- Yes --> I
    K -- No --> L[Click Checkout
POST /cart/checkout + Bearer token]
    L --> M[201 returns order_id + total
cart is emptied]
    M --> N([Test passes])

    I -. without token .-> X[401 Missing Bearer token]
    L -. empty cart .-> Y[400 Cart is empty]

Steps to perform (static client)

Do these in order. The client shows the raw API response for every action, so you can confirm each status code.

#	What you do	Expected result
1	Open `http://localhost:3000`	Page loads; Products lists 4 items with prices; auth badge says signed out.
2	Look at cart actions while signed out	The Add buttons and Checkout are disabled.
3	Enter email + password (≥ 6 chars), click Sign up	`201` with `{ id, email, token }`; badge flips to signed in; Add/Checkout enable.
4	Click Add on two different products	Each returns `200`; the Cart list and Total update.
5	Click Add on a product already in the cart	Its quantity increments (no duplicate line).
6	Click Checkout	`201` with `{ order_id, total_cents }`; cart empties; Total back to `$0.00`.
7	Click Checkout again (empty cart)	`400 Cart is empty`.
8	Click Sign out	Badge says signed out; cart actions disabled again.
9	Reload the page after signing in	You stay signed in (token in `localStorage`) and the cart reloads.

Negative / auth checks

#	What you do	Expected result
10	Sign in with a wrong password	`401 Invalid credentials`; stays signed out.
11	Sign up with the same email twice	Second attempt returns `409 Email already registered`.
12	Sign up with a 3-char password	`400` validation error.

A run is successful when steps 1–12 all match their expected results.

Bonus Build it yourself — no guide provided

This part is not built. You implement it yourself. There is no walkthrough, no starter code, and no hints about how — those design decisions are yours. Only the requirements and what we check are below.

Task 1 — Product page

Build a product page for an individual item.
It must render all of the product's details — every field the catalog provides, including its images (there is more than one) — laid out as a real product page, not raw JSON.
The products are already pre-seeded and their full details are available from the API. Finding and using that data is part of the task.

Task 2 — Ratings

A signed-in user can give a product a star rating from 1 to 5.
A user has at most one rating per product. Rating the same product again updates their previous rating (it must not create a duplicate).
Each product's average rating and number of ratings are publicly viewable — anyone can see them without signing in (e.g. shown on the product page).
Invalid input is rejected: a rating outside 1–5, a non-integer, or an unknown product.
An unauthenticated attempt to submit a rating is rejected (viewing stays public).
Whatever endpoints you add must be documented so they appear in /docs.

Task 3 — Comments

A signed-in user can add comments to a product (a user may leave more than one).
A product's comments are publicly viewable — anyone can read them without signing in (e.g. listed on the product page).
Each comment shows who wrote it and when.
Invalid input is rejected: an empty comment, or a comment on an unknown product.
An unauthenticated attempt to post a comment is rejected (reading stays public).
Whatever endpoints you add must be documented so they appear in /docs.

How it will be checked

The product page shows the product's images, description, category and price — all of them.
Without signing in, the product's average rating, rating count, and comments are visible.
Sign in, rate a product 4, then read it back — the average reflects it and the count is 1.
Rate the same product again with 2 — the count stays 1 and the average becomes 2 (updated, not added).
A second user rates the same product 5 — the count is 2 and the average is the mean of the two.
Sending a rating of 0, 6, 3.5, or for a non-existent product returns a 4xx error.
Sign in and post a comment; it then appears in the public comment list with the author and timestamp.
Submitting a rating or comment without a bearer token returns 401.

No further direction will be given. Make reasonable design choices and justify them if asked.

Alternative: scripted check with curl

BASE=http://localhost:3000

# 1. sign up and capture the JWT
TOKEN=$(curl -s -X POST $BASE/auth/signup \
  -H 'content-type: application/json' \
  -d '{"email":"curl@example.com","password":"hunter2pw"}' \
  | node -pe 'JSON.parse(require("fs").readFileSync(0)).token')

# 2. a cart call without the token must be rejected (expect 401)
curl -s $BASE/cart

# 3. add an item, then view the cart (expect the line + total)
curl -s -X POST $BASE/cart/items -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"productId":1,"quantity":2}'
curl -s $BASE/cart -H "Authorization: Bearer $TOKEN"

# 4. check out (expect 201 with order_id + total_cents)
curl -s -X POST $BASE/cart/checkout -H "Authorization: Bearer $TOKEN"