# Order-change delivery contract

An illustrative Mottobits engineering example. This is a review template, not client work, a completed engagement, or a claim that tests have passed.

## Change
Allow an authenticated order editor to change the quantity of an existing order. A read-only user must not change the order through the UI or a direct API request.

## Agree before implementation
- Which order states allow edits, and which roles have permission?
- What quantity range is valid? What should happen to totals and reservations?
- Which system is authoritative for permissions and order state?
- What are the existing API contract, side effects, and audit requirements?
- Which isolated environment, editor/viewer accounts, and disposable orders can QA use?

## Acceptance checks
1. An editor updates an editable order; the persisted quantity matches the request.
2. A read-only user receives a rejection for the same update; a separate authorized read confirms the quantity did not change.
3. An unauthenticated request is rejected before any change occurs.
4. Invalid quantities fail without altering the order or producing partial side effects.
5. Repeating a failed request leaves the order unchanged.

Confirm exact HTTP responses against the application's agreed API contract.

## Illustrative Playwright API check
Project fixtures and helpers below must be implemented in the target repository. This fragment is not a standalone runnable suite. The order fixture must provide a different quantity that is valid for an editable order. Verify the editor success case on a separate equivalent order so a general update failure cannot masquerade as authorization protection.

```ts
test('read-only user cannot change an order', async () => {
  const before = await readOrderAsEditor(order.id);
  const quantity = order.validNewQuantity;
  expect(quantity).not.toBe(before.quantity);
  const response = await viewer.patch(order.url, {
    data: { quantity },
  });
  expect(response.status()).toBe(403);
  const after = await readOrderAsEditor(order.id);
  expect(after.quantity).toBe(before.quantity);
});
```

A disabled UI button is not evidence of server-side authorization. Assert the API outcome and persisted state. Use separate role-scoped clients; do not reuse administrator authentication for the rejection test.

## Handover evidence
- Reviewed diff tied to the acceptance checks.
- Repeatable data setup and teardown; environment and fixture assumptions.
- Test command, run identifier, commit SHA, and actual CI outcome.
- Failure traces or screenshots with credentials and customer data removed.
- Open risks, omitted checks, and a rollback or recovery plan.

## Controls outside the tests
Use required CI checks, protected test/workflow changes, and agent credentials that cannot bypass those controls. Document the expected test inventory so deleting or skipping the test cannot quietly satisfy the gate. No test suite can guarantee enforcement if an actor has permission to disable or bypass it.

Mottobits · Adnan Rafiq & ChatGPT