BookNest requirements

All data entered into BookNest MUST be synthetic. Users MUST NOT enter real personal, payment, customer, production, confidential, or regulated information.

BookNest MUST identify itself as demonstration software and MUST NOT imply affiliation with a similarly named company, product, or service.

The storefront MUST display money using US dollar formatting. Backend monetary values MUST be calculated in integer cents and returned as decimal dollar values.

Mutable state MUST be scoped by a Test Run ID. State from one valid Test Run ID MUST NOT affect another Test Run ID.

When no run identifier is supplied, the API MUST use shared-demo. Automated tests SHOULD NOT use shared-demo because concurrent runs may interfere with one another.

At most one Test Lab scenario MAY be active for a Test Run ID at a time.

Checkout MUST NOT collect real card details, contact a payment provider, initiate a financial transaction, or fulfil an order.

The normal catalogue MUST contain 40 deterministic synthetic books across these categories:

Fiction, Mystery, Science, History, Business, Design, Cooking, and Young Adult.

Each normal book MUST have:

• numeric ID;
• title and author;
• category;
• current price and optional original price;
• rating and review count;
• stock quantity;
• format (Hardcover, Paperback, or E-book);
• publication year;
• synthetic ISBN-like identifier;
• description and cover palette;
• optional badge (Bestseller, New, or Staff pick).

The storefront MUST show book title, author, price, rating, availability, format/category context, and an add action. Out-of-stock books MUST show an unavailable state and MUST NOT be addable.

Search MUST be case-insensitive and match title, author, ISBN, or category. Typing more than one character SHOULD display at most five title/author suggestions.

The storefront MUST support:

• category;
• maximum price from $10 through $50 in $1 steps;
• in-stock-only filtering;
• combined filtering with search.

Clearing filters MUST restore the empty query, All categories, maximum price $50, availability filter off, and Featured sorting.

The storefront MUST support:

• featured;
• price low to high;
• price high to low;
• highest rated;
• newest.

The storefront MUST display eight matching books per page and MUST reset to page one when search, filter, or sorting criteria change.

When no books match, the storefront MUST display a no-results state and a control that clears all filters.

Selecting a book MUST open product details containing title, author, category, format, rating, reviews, description, year, ISBN, availability, price, and an add action when stock is available.

GET /api/v1/books MUST support query, category, availability, maximum price, sorting, page, and page-size parameters. Page size MUST be constrained to 1..100.

GET /api/v1/books/{id} MUST return the requested book or 404 BOOK_NOT_FOUND.

Anonymous carts MUST be identified by the combination of Test Run ID and X-Client-Id. The browser SHOULD retain a stable generated client ID in local storage.

Adding a book MUST increase its existing quantity by the requested amount. The resulting quantity MUST NOT exceed current stock.

The API MUST return:

• 404 BOOK_NOT_FOUND for an unknown book;
• 409 OUT_OF_STOCK for a book with no stock;
• 409 STOCK_LIMIT when the resulting quantity exceeds stock.

Setting quantity MUST accept a non-negative integer. Quantity zero MUST remove the line. A negative or non-integer quantity MUST return 422 INVALID_QUANTITY.

The cart API MUST support removing one book by ID and clearing all books when no ID is supplied.

When a book is added or its quantity is updated, the cart MUST store the current unit price as a snapshot for later conflict detection.

Adding, updating, or removing cart contents MUST clear the applied promotion.

The cart MUST calculate:

• subtotal = sum(price snapshot × quantity);
• discount = 10% of subtotal when BOOK10 is valid;
• shipping = $4.99 when subtotal is greater than $0 and less than $40;
• shipping = $0 when subtotal is $40 or more;
• total = subtotal - discount + shipping.

Cart updates in one browser tab SHOULD cause another BookNest tab using the same Test Run ID and browser storage context to reload its cart.

BOOK10 MUST be case-insensitive and MUST apply a 10% discount to the current cart.

EXPIRED20 MUST return 422 PROMOTION_EXPIRED.

Any other promotion code MUST return 422 PROMOTION_UNKNOWN.

Registration MUST accept first name, last name, email, password, and optional password confirmation.

The API MUST enforce:

• non-empty first and last names;
• a syntactically valid email;
• password length of at least eight characters;
• at least one uppercase letter and one digit;
• matching confirmation when confirmation is supplied;
• email uniqueness within the Test Run ID.

Email addresses MUST be trimmed and stored/compared in lowercase.

The seeded synthetic account MUST be available independently in each Test Run ID:

Email: customer@example.com
Password: Password123!
Name: Alex Morgan

The account MAY be created lazily on the first login attempt for that run.

Successful login MUST create a bearer token valid for one hour and return the synthetic user and expiry timestamp. Invalid credentials MUST return 401 INVALID_CREDENTIALS.

Successful login MUST merge the anonymous cart identified by X-Client-Id into the authenticated customer cart, then remove the anonymous cart state. The response MUST indicate whether a cart was merged.

Order listing, order creation, and cancellation MUST require a valid, unexpired bearer session from the same Test Run ID.

Logout MUST invalidate a supplied bearer token when present and MUST be idempotent when no token is supplied.

The storefront SHOULD retain the current synthetic bearer token and user in local storage. When an authenticated API request returns 401, the storefront MUST return to the unauthenticated state and require login again.

An unauthenticated user starting checkout MUST be prompted to sign in. After successful authentication, the user SHOULD resume checkout without losing the cart.

Order placement MUST require street address, city, and postal code. Missing fields MUST return 422 DELIVERY_REQUIRED.

Checkout with no cart lines MUST return 422 EMPTY_CART.

Order creation MUST accept Idempotency-Key. Repeating a request with the same key and Test Run ID MUST return the existing order and MUST NOT create or charge a second order.

Checkout MUST compare each current catalogue price with the cart price snapshot. A mismatch MUST return 409 PRICE_CHANGED with previous and current price information.

Checkout MUST reject a quantity greater than available stock with 409 INVENTORY_CONFLICT.

A successful order MUST:

• use an ID formatted as BN-<UTC year>-<six digits>;
• have initial status Confirmed;
• persist item quantities and unit-price snapshots;
• decrement inventory;
• clear cart lines and promotion state;
• appear in the authenticated customer's order history;
• return HTTP 201 for first creation.

Order history MUST contain only orders belonging to the authenticated customer and current Test Run ID, newest first.

An authenticated customer MAY cancel their own order. Cancellation MUST set status to Cancelled and restore item quantities to inventory. Repeating cancellation MUST return success without restoring inventory twice.

An absent order, another customer's order, or an order from another Test Run ID MUST return 404 ORDER_NOT_FOUND.

The backend MUST resolve the Test Run ID in this order:

1. X-Test-Run-Id request header;
2. runId URL query parameter;
3. shared-demo.

Valid IDs are 1–80 characters containing letters, digits, ., _, :, or -. Invalid values MUST fall back to shared-demo.

Users, sessions, carts, cart items, inventory, orders, and scenario state MUST be isolated by Test Run ID.

The storefront Reset demo data action MUST create a new unique manual Test Run ID and clear the current browser session view. It does not delete the previous run from the database.

POST /api/v1/test/reset MUST require X-Test-Admin-Key and MUST delete users, sessions, carts, inventory, orders, order items, and scenario state only for the supplied Test Run ID.

Scenario read/write and destructive reset operations MUST require an X-Test-Admin-Key value equal to the encrypted deployment secret BOOKNEST_TEST_ADMIN_KEY.

The secret MUST NOT be committed to source control, placed in URLs, or included in screenshots and public test artifacts.

The Test Lab UI MUST keep the entered admin key only in the current in-memory browser state. It MUST NOT save the key to local storage.

The active scenario, normalized settings, request count, and update time MUST be stored per Test Run ID.

The scenario API MUST:

• reject unsupported scenario names with 422 UNKNOWN_SCENARIO;
• discard unsupported setting keys;
• fill missing values with documented defaults;
• clamp numeric values to documented minimum and maximum values;
• trim text and limit it to 240 characters.

Business API calls that apply scenarios MUST increment the scenario request counter. Initial storefront catalogue and cart calls count toward intermittent, rate-limit, and session-expiry thresholds.

• General transport scenarios SHOULD affect catalogue, authentication, cart, promotion, order, and cancellation APIs that invoke the common scenario handler.
• Catalogue-data scenarios MUST affect catalogue responses.
• inventory-conflict, price-change, and payment-decline MUST affect order creation.
• expired-session MUST affect authenticated session resolution.

The storefront MUST activate Intentional Defects Mode only through the comma-separated defects query parameter. API clients MUST be able to activate the same packs through either the query parameter or the X-Test-Defects header.

Examples:

/?defects=smoke
/?defects=ui,functional
/api/v1/books?defects=api
X-Test-Defects: api,state

The following packs and stable defect identifiers MUST be supported:

Requests without a supported defects value MUST retain the documented normal behavior. Activating defects for one browser URL or API request MUST NOT globally enable them for other users or test runs.

Every intentional defect MUST define a stable identifier, title, expected behavior, and deliberately defective behavior. The storefront MUST show an Intentional defect mode banner and expose active pack names and defect IDs through data-defect-packs and data-defect-ids on the application root.

The same pack, input, state, and Test Run ID MUST produce the same intentional behavior, except for identifiers and timestamps already documented as dynamic. Removing the defects parameter or X-Test-Defects header MUST restore normal behavior without a database reset.

Multiple supported packs MAY be combined with commas. Duplicate names MUST activate a pack only once. Names MUST be matched case-insensitively after surrounding whitespace is removed. Unknown or empty pack names MUST be ignored and MUST NOT produce an application error.

When the storefront is opened with active packs, its business API requests MUST send the equivalent X-Test-Defects value. Direct API tests MAY use either the header or query parameter. If both are supplied, the header MUST take precedence.

The Test Lab MUST list all supported packs, descriptions, stable IDs, and launch links without requiring the admin key. GET /api/v1/test/defects MUST return the same machine-readable catalogue plus the packs and IDs active for that request.

Intentional defect packs MUST remain separate from persisted Test Lab scenarios. Activating or disabling a pack MUST NOT change the stored scenario or scenario request counter. Packs MAY be combined with ?ui=v2 and a Test Run ID, for example /?ui=v2&runId=poc-001&defects=ui,functional.

Defect activation MUST NOT require, transmit, display, or persist BOOKNEST_TEST_ADMIN_KEY. It MUST NOT disable the synthetic-data notice, introduce real payment processing, expose secrets, weaken run isolation, or mutate state outside the supplied Test Run ID.

QA engineers and automation tools SHOULD:

1. execute the target journey without defect activation and record a passing baseline;
2. rerun it with exactly one defect pack and a clean Test Run ID;
3. map each observed failure to a documented DEF-* identifier;
4. capture evidence, expected behavior, actual behavior, and recovery diagnostics;
5. remove defect activation and confirm that the baseline passes again;
6. combine packs only after independent pack coverage is understood.

The storefront MUST activate resilience mode only when the URL contains ui=v2. The root element MUST expose data-ui-version="v1" or data-ui-version="v2".

The default UI and ?ui=v2 MUST preserve catalogue data, search results, pricing, stock rules, authentication, cart, promotions, checkout, orders, stable test IDs, and accessible action intent.

?ui=v2 intentionally changes:

• header action order;
• search placeholder and styling;
• catalogue headings;
• filter position and category control type;
• mobile filter side and wording;
• result-toolbar order;
• product-card layout and DOM hierarchy;
• selected labels, icons, and action wording;
• checkout action wording.

Tests SHOULD assert business outcomes rather than depend exclusively on visible copy, CSS classes, child positions, or brittle XPath expressions.

The following stable UI hooks are currently available:

• data-testid="search-input";
• data-testid="book-grid";
• data-testid="book-card-<bookId>";
• data-testid="add-to-cart-<bookId>";
• data-testid="checkout-button";
• data-testid="place-order-button".

Accessible names SHOULD be preferred where they express user intent and remain equivalent across modes.

Business endpoints MUST use /api/v1. /api/openapi MUST generate an OpenAPI 3.1 document using the hostname of the current request.

JSON responses MUST use application/json; charset=utf-8 and cache-control: no-store.

Handled errors MUST use this shape:

{
  "error": {
    "status": 422,
    "code": "EXAMPLE_CODE",
    "message": "Human-readable explanation.",
    "details": null
  },
  "traceId": "generated-uuid"
}

Malformed JSON MUST return 400 INVALID_JSON.

Detailed bodies, examples, and status codes are maintained at /api-docs and /api/openapi.

When the browser exposes document.modelContext, the storefront SHOULD register:

Agents and automation tools MUST:

• use synthetic data only;
• prefer staging for destructive and failure tests;
• use a unique Test Run ID per execution or parallel worker;
• keep X-Test-Run-Id identical across setup, UI, API, and cleanup steps;
• keep a stable X-Client-Id through anonymous-cart and login-merge steps;
• never print, commit, record, or place X-Test-Admin-Key in a URL;
• restore the scenario to normal or reset the run after failure-injection tests;
• treat dynamic UUIDs, tokens, timestamps, and order numbers as patterns rather than fixed values;
• account for initial page-load requests when using request-count scenarios;
• use the same business assertions against the default UI and ?ui=v2.

Automation SHOULD prefer, in order:

1. accessible role and accessible name;
2. stable data-testid hooks;
3. semantic labels and nearby business context;
4. visible text when wording is part of the requirement.

Automation SHOULD avoid generated CSS classes, absolute XPath, DOM child indexes, and assumptions that v1/v2 share identical visible text or hierarchy.

Tests MUST NOT hard-code:

• bearer tokens;
• generated user IDs;
• session-expiry timestamps;
• order numbers;
• trace IDs;
• scenario update timestamps.

Tests SHOULD extract and reuse these values or validate their documented formats.

The storefront, API documentation, About page, and Test Lab MUST remain usable at desktop and mobile viewport sizes. Mobile filters MUST be available through a side panel.

Interactive controls SHOULD expose meaningful accessible names. Dialogs, sheets, forms, alerts, listboxes, checkboxes, radios, selects, and buttons SHOULD be keyboard-operable and programmatically identifiable.

Seed catalogue values and Test Lab scenarios MUST be deterministic for identical inputs, except explicitly dynamic identifiers and timestamps.

Independent automation executions MUST be able to run in parallel using different Test Run IDs without state collision.

Test-control APIs MUST reject a missing or incorrect admin key with 403 ADMIN_KEY_REQUIRED. Sensitive deployment secrets MUST be stored as encrypted runtime secrets, not repository variables.

API responses MUST not be cached. Test tools SHOULD isolate learned locators/caches between environments when DOM or configuration differs.

The storefront MUST show observable error feedback for catalogue, cart, authentication, promotion, checkout, and order failures. Catalogue failure MUST offer a retry action.

1. Start with a unique Test Run ID and client ID.
2. Add an available book anonymously.
3. Start checkout.
4. Sign in using the demo account.
5. Verify anonymous cart merge and preserved checkout intent.
6. Submit synthetic delivery information.
7. Verify one confirmed order, cleared cart, order history, and reduced stock.

1. Register a unique synthetic customer.
2. Verify automatic login through the storefront flow.
3. Add books and apply BOOK10.
4. Verify subtotal, discount, shipping, and total.
5. Place the order and verify its dynamic ID and persisted history.

1. Prepare an authenticated cart.
2. Submit the same order twice using one Idempotency-Key.
3. Verify only one order exists and the replay reports the existing order.

1. Create an order.
2. Record post-purchase inventory.
3. Cancel the order.
4. Verify Cancelled status and restored inventory.
5. Cancel again and verify inventory is not restored twice.

1. Add a book to the cart.
2. Activate price-change for the same Test Run ID.
3. Attempt checkout and verify 409 PRICE_CHANGED.
4. Return the scenario to normal and refresh the cart price.
5. Complete checkout successfully.

1. Execute catalogue search, add-to-cart, login, and checkout in v1.
2. Execute the same business journey with ?ui=v2 and a clean run.
3. Verify equivalent outcomes despite wording, layout, control-type, and DOM changes.

1. Create state under run A.
2. Open run B with the same browser/client identity.
3. Verify run B cannot see run A's user, cart, inventory, order, or scenario state.

1. Activate each transport scenario through the protected scenario API.
2. Exercise the matching business endpoint using the same Test Run ID.
3. Verify status, response contract, delay/header behavior, UI feedback, and retry/recovery.
4. Reset the run during teardown.

1. Execute the baseline smoke flow without a defects parameter and verify it passes.
2. Repeat the flow with ?defects=smoke and verify the five documented failures are detected and mapped to their stable defect IDs.
3. Exercise each remaining pack independently using a clean Test Run ID.
4. Activate the API pack through X-Test-Defects: api and verify contract tests report the documented status, missing-field, type, not-found, and idempotency violations.
5. Remove defect activation and verify the baseline passes again without resetting stored scenario state.