QA Test Scenarios

Status

This document is FINAL and ENFORCEABLE for QA, UAT, and access-control validation.

It converts the architecture, access matrix, middleware, cache rules, admin flows, and migration assumptions into concrete test scenarios.

It complements:

• 2.4.-Access-Control-Integration.md
• 2.5.-Access-Matrix.md
• 2.6.-Middleware-Implementation.md
• 2.7.-Access-Caching-Strategy.md
• 2.8.-Admin-Platform-Spec.md
• 2.9.-Migration-Plan-Mongo-to-Auth-Core.md
• 3.-Frontend-Implementation.md
• 3.1.-Frontend-Tasks-Breakdown.md

---

1. Purpose

This document defines:

• test cases
• expected responses
• expected UI outcomes
• edge cases
• failure behavior
• regression scenarios

It is designed so QA does not need to infer the access model from architecture docs.

---

2. Core access rule under test

A tenant-scoped request is allowed only if all are true:

1. JWT is valid
2. x-org is present and valid
3. user has valid membership in the company
4. company owns the module
5. membership is granted the module
6. membership has the required permission
7. Auth access resolution is available

---

3. Expected status code contract

Status	Meaning	Typical QA interpretation
200 / 201	Success	Request allowed
400	Bad request	Missing or invalid request context, usually x-org
401	Unauthorized	Missing/invalid/expired token
403	Forbidden	Authenticated, but access denied
404	Not found	Resource not found or intentionally hidden depending on endpoint policy
409	Conflict	Business conflict, not access issue
503	Service unavailable	Auth/Core/dependency not available for access resolution

---

4. Test data setup requirements

QA should have the following reusable test fixtures.

4.1 Companies

Create at minimum:

• Company A → Basic + Finance + Market
• Company B → Finance only
• Company C → Basic only
• Company D → no active entitlements
• Company E → Venue + AI only

---

4.2 Users / memberships

Create at minimum:

• Platform Admin User
• Tenant Superadmin User
• Admin User
• Finance User
• Manager User
• Submitter/User
• User with no membership
• Vendor User (if vendor routes tested)

---

4.3 Membership access patterns

At minimum, prepare:

• User 1 → Company A → Basic + Finance + Market
• User 2 → Company A → Finance only
• User 3 → Company A → Basic only
• User 4 → Company A → Finance permission revoked
• User 5 → Company B → Finance only
• User 6 → Company C → Basic only
• User 7 → Company D → no modules
• User 8 → Company E → Venue only
• User 9 → Company E → AI only

---

4.4 Permission examples

Use permission keys such as:

• basic.dashboard.view
• basic.event.view
• basic.event.create
• finance.expense.view
• finance.expense.create
• finance.expense.edit
• market.contract.view
• market.contract.approve
• venue.calendar.view
• ai.chat.use

---

5. Happy path test scenarios

5.1 Login → bootstrap → access load

Scenario

User logs in successfully and frontend loads access.

Steps

1. login with valid credentials
2. receive JWT + refresh token
3. call /auth/me
4. select company
5. call /auth/me/access with x-org

Expected

• login returns 200
• /auth/me returns 200
• /auth/me/access returns 200
• frontend receives effective modules and permissions
• module tiles render according to effective access

---

5.2 Basic module allowed

Scenario

User has Basic through company entitlement and membership grant.

Preconditions

• company owns Basic
• membership granted Basic
• user has basic.dashboard.view

Request

GET /api/basic/dashboard
Authorization: Bearer <token>
x-org: <companyId>

Expected

• 200
• backend executes
• frontend shows Basic module

---

5.3 Finance module allowed

Scenario

User has Finance entitlement and membership grant.

Preconditions

• company owns Finance
• membership granted Finance
• user has finance.expense.view

Request

GET /api/finance/expenses
Authorization: Bearer <token>
x-org: <companyId>

Expected

• 200
• finance page loads
• create button shown only if finance.expense.create also exists

---

5.4 Standalone module without Basic

Scenario

Company has Finance only, no Basic.

Preconditions

• company owns Finance only
• membership granted Finance
• no Basic entitlement

Expected

• Core App hidden
• Finance module visible
• finance routes still succeed
• Basic routes return 403

---

6. JWT / authentication tests

6.1 Missing token

Request

No Authorization header

Expected

• backend returns 401
• frontend redirects to login or shows unauthenticated state

---

6.2 Invalid token

Request

Malformed bearer token

Expected

• 401
• error code indicates unauthorized
• request not executed

---

6.3 Expired token

Expected

• initial request returns 401
• frontend attempts refresh if flow supports it
• if refresh succeeds, request may retry
• if refresh fails, user is logged out

---

6.4 Wrong issuer / audience

Expected

• 401
• request denied before access resolution

---

7. x-org / company context tests

7.1 Missing x-org

Request

Tenant request without x-org

Expected

• 400
• error clearly indicates missing x-org
• backend must not infer default company

---

7.2 Invalid x-org format

Expected

• 400
• request rejected before business logic

---

7.3 Company switch

Scenario

User switches from Company A to Company B

Steps

1. current access loaded for Company A
2. switch active company
3. frontend calls /auth/me/access again with new x-org

Expected

• old access state discarded
• new effective modules loaded
• visible modules update immediately
• subsequent requests carry new x-org

---

8. Membership and role tests

8.1 User not in company

Preconditions

• valid user
• valid token
• user has no membership in selected company

Expected

• /auth/me/access or backend access resolution returns 403
• backend route returns 403
• frontend shows access denied / company not accessible

---

8.2 Tenant Superadmin with granted module

Expected

• access allowed only if membership has module
• role alone must not auto-grant every module if architecture forbids auto-grant

---

8.3 Finance role without Finance module grant

Preconditions

• user role indicates finance-oriented scope
• company owns Finance
• membership NOT granted Finance

Expected

• Finance module hidden
• Finance route returns 403

---

8.4 Submitter with explicit Finance grant

Preconditions

• user is low-role / submitter
• company owns Finance
• membership explicitly granted Finance
• permission exists

Expected

• Finance module allowed
• only permitted actions available
• role does not block basic usage if grant exists

---

9. Entitlement tests

9.1 Company does not own module

Preconditions

• membership granted module
• company does NOT own module

Expected

• effective access excludes module
• frontend hides module
• backend route returns 403

---

9.2 Entitlement removed after previous access existed

Scenario

Company previously had Finance, then Finance removed.

Steps

1. user has cached Finance access
2. admin removes Finance add-on
3. entitlementVersion changes
4. next request happens

Expected

• stale cache not reused
• access rebuilt
• Finance removed from effective modules
• route returns 403
• frontend refresh removes Finance UI

---

9.3 Basic removed but standalone module remains

Preconditions

• company loses Basic
• company still owns Finance

Expected

• Core App hidden
• Finance remains accessible if membership granted
• Basic endpoints return 403

---

10. Permission tests

10.1 Permission allowed

Preconditions

• module allowed
• permission present

Expected

• route returns 200
• UI action visible

---

10.2 Permission missing

Preconditions

• module allowed
• permission absent

Expected

• route returns 403
• UI action hidden if frontend refreshed correctly

---

10.3 Revoked permission

Scenario

Permission existed, then removed.

Steps

1. user loads page with permission
2. admin revokes permission
3. accessVersion changes
4. user retries action

Expected

• stale access invalidated
• next protected action returns 403
• frontend refresh hides action

This is a critical regression scenario.

---

10.4 Permission belongs to disabled module

Preconditions

• permission exists in raw assignment
• module not effective

Expected

• permission must not grant access by itself
• backend denies route with 403

---

11. Delegation / admin-management tests

11.1 Superadmin grants allowed module

Expected

• success
• accessVersion changes
• affected user cache invalidated

---

11.2 Admin tries to grant module outside delegation scope

Expected

• 403
• no DB change
• no accessVersion bump for target user

---

11.3 Manager tries to grant unauthorized permission

Expected

• 403
• audit entry created if policy requires
• no change persisted

---

11.4 User without delegation attempts user-management endpoint

Expected

• 403

---

12. Cache tests

12.1 Cache hit

Preconditions

• identical user/company/version inputs
• access already cached

Expected

• Auth returns cached access successfully
• response still correct
• no stale mismatch

---

12.2 tokenVersion change invalidates cache

Steps

1. user has cached access
2. tokenVersion increases (logout-all / session reset)
3. same route requested

Expected

• old key not reused
• access rebuilt
• request succeeds only if new session valid

---

12.3 entitlementVersion change invalidates cache

Steps

1. company entitlement changes
2. entitlementVersion increments
3. request executed

Expected

• cache miss / rebuild
• new access reflects entitlement change

---

12.4 accessVersion change invalidates cache

Steps

1. membership permissions change
2. accessVersion increments
3. request executed

Expected

• old cached access not reused
• rebuilt access reflects new grants

---

12.5 Redis unavailable but recompute succeeds

Expected

• request still succeeds
• no incorrect 403/503 if recomputation is possible

---

12.6 Redis unavailable and recompute fails

Expected

• 503
• request denied
• fail-closed respected

---

13. Dependency failure tests

13.1 Auth unavailable

Expected

• protected backend routes return 503
• no optimistic allow
• frontend shows temporary unavailable state

This is a required edge case.

---

13.2 Core unavailable during access resolution

Expected

• Auth cannot resolve entitlements
• Auth returns failure
• backend returns 503
• frontend shows retry state

This is a required edge case.

---

13.3 Partial malformed response from Auth

Expected

• backend treats access resolution as failed
• returns 503
• no fallback to guessed access

---

14. Frontend UX tests

14.1 Module hidden when not effective

Expected

• module tile absent
• direct route attempt denied or redirected

---

14.2 Stale UI after revoke

Scenario

UI still shows button briefly after revoke.

Expected

• backend action returns 403
• frontend refreshes access
• button disappears

---

14.3 Company switch rerenders app shell

Expected

• module menu updates
• route guards update
• stale screens are not preserved incorrectly

---

14.4 Access denied messaging

Expected

• clear UX message
• no generic crash
• no misleading “not found” unless intentionally designed

---

15. Admin platform tests

15.1 Create package

Expected

• package created in Core
• visible in admin catalog
• no direct user access change until company assigned

---

15.2 Assign add-on to company

Expected

• entitlementVersion increments
• company cache invalidation triggered
• users see module after next access rebuild only if granted

---

15.3 Delegation limit change

Expected

• accessVersion changes for affected users if model requires it
• UI controls update after refresh
• unauthorized grants now blocked

---

15.4 Company approval

Expected

• approved company becomes active
• users can load company after proper membership/access exists

---

16. Vendor / non-tenant tests

16.1 Vendor route without vendor token

Expected

• unauthorized or forbidden according to vendor auth model

---

16.2 Tenant route with vendor token

Expected

• denied
• vendor auth must not satisfy tenant access model

---

16.3 Public route

Expected

• no JWT needed
• no x-org needed
• protected data not exposed

---

17. Migration regression tests

17.1 Legacy user mapped to Auth UUID

Expected

• membership joins work
• access resolution works
• old Mongo identity is no longer required at runtime

---

17.2 Company mapping after migration

Expected

• canonical company id used in x-org
• no mixed legacy company identifiers in active flows

---

17.3 Old permission model removed

Expected

• access decisions no longer rely on legacy backend-local permission truth
• Auth/Core model is authoritative

---

18. Suggested test case format

Use this format for execution tracking:

Test Case ID

Example: QA-ACCESS-001

Title

Example: Missing x-org on tenant route returns 400

Preconditions

• user exists
• route is tenant-scoped

Steps

1. send request without x-org

Expected

• HTTP 400
• no business logic execution

Notes

• mapped to section 7.1

---

19. Example detailed cases

QA-ACCESS-001 — Missing x-org

Preconditions

• valid user
• valid token
• tenant route /api/finance/expenses

Steps

1. send GET request without x-org

Expected

• status 400
• body indicates validation error
• no downstream DB logic executed

---

QA-ACCESS-002 — Revoked permission

Preconditions

• user previously had finance.expense.create
• company owns Finance
• membership has Finance
• permission revoked before request

Steps

1. user clicks Create Expense
2. frontend sends request
3. backend resolves fresh access

Expected

• status 403
• no create occurs
• frontend refreshes access and hides create action

---

QA-ACCESS-003 — Entitlement removed

Preconditions

• company previously had Market
• Market entitlement removed
• user still has stale UI state

Steps

1. user opens Market page or sends Market API request

Expected

• fresh access resolution excludes Market
• status 403
• frontend removes Market module after refresh

---

QA-ACCESS-004 — Auth down

Preconditions

• backend depends on Auth for access
• Auth unavailable

Steps

1. send protected request

Expected

• status 503
• request denied
• no optimistic allow

---

20. Final rule

QA must always validate the full chain:
JWT → x-org → membership → entitlement → module → permission → dependency health

---

21. Final one-line summary

A request is only truly valid when identity, company context, entitlements, grants, permissions, and dependency health all succeed together.