Developer Testing

Use this checklist when changing authentication, merchant navigation, or order dispatch. Test with the dedicated demo accounts and never reuse them for real deliveries.

Automated checks

Run commands from the repository root unless noted otherwise.

# Focused DEMO assignment-policy tests
node --test server/services/agentEligibilityService.test.js

# SPAs affected by authentication and merchant UI behavior
cd spa_wasal_dashboard && npm run build && cd ..
cd spa_merchant_dashboard && npm run build && cd ..
cd spa_delivery_partner_dashboard && npm run build && cd ..
cd spa_customer && npm run build && cd ..

# Documentation
cd docs && npm run build && cd ..

# Final source-diff check
git diff --check

The focused policy suite should pass all six cases. Run the repository's complete test suite from the VS Code Testing view before release. Production builds generate files under each SPA's dist directory and VitePress generates docs/.vitepress/dist; do not include generated output unless the deployment process explicitly requires it.

Automatic driver assignment pools

A delivery-partner admin can configure an ordered driver pool for each merchant from /delivery-partner/merchants. New live B2C orders and activated drafts check drivers in priority order and assign the first driver who is active, belongs to the delivery partner, supports the payment method, passes DEMO isolation, and is below the combined active B2C/B2B workload limit. Online presence is not required.

If no configured driver qualifies, the order remains pending. The merchant relationship's Auto-notify Agents grid setting then determines whether eligible agents receive a prospect notification. Test both successful direct assignment and fallback to pending whenever pool eligibility rules change.

DEMO merchant assignment isolation

The merchant accounts with codes DEMO and DEMO2 are isolated from the normal agent pool. Their B2C and B2B orders may only be assigned to Demo Driver, whose phone is configured by TEST_AGENT_PHONE. This rule is enforced by the API; hiding agents in a dashboard is not the security boundary.

Configure the demo login emails and driver phone in the server environment before starting the API. Every comma-separated TEST_MERCHANT_EMAIL value receives the fixed demo OTP, and TEST_AGENT_PHONE must be the normalized phone of exactly one active delivery-partner agent. Restart the server after changing either value.

Both DEMO merchants are linked to Demo Delivery Partner, and Demo Driver belongs to that partner. Use either configured merchant email with TEST_MERCHANT_OTP for the merchant dashboard. The operations account uses TEST_DELIVERY_PARTNER_EMAIL; the main admin uses TEST_DELIVERY_PARTNER_ADMIN_EMAIL. Both Demo Delivery Partner accounts use TEST_DELIVERY_PARTNER_OTP. The operations account's civil-ID login identifier is the dedicated test civil ID configured on that account.

1. Create an order from the Demo Merchant dashboard or integration API using its pk_live_ key.
2. Open the order as the Demo Delivery Partner operations manager and assign it to Demo Driver.
3. Confirm the order is visible on the B2C order list and operations map.
4. Accept and complete it as Demo Driver in the agent app.
5. Confirm the final status in the merchant dashboard and COD reconciliation when applicable.

The Demo Delivery Partner user has the operations_manager role. This role is limited to operational oversight: Dashboard, Orders, B2B Orders, Map, and COD Cash Reconciliation. It may also view its own profile. Management, reporting, settings, settlements, revenue, and Wasal payment pages and APIs require delivery_partner_admin. Verify both navigation visibility and direct page/API authorization. The delivery_partner_admin role retains full access.

The restriction applies to:

• Delivery-partner assignment and reassignment
• Agent prospect lists and self-acceptance
• New-prospect push notifications
• B2B assignment
• Admin order creation and update

The restriction is one-way: Demo Driver may still handle a non-DEMO order if operations explicitly assigns one.

Assignment test matrix

Scenario	Expected result
Regular agent loads prospects	No DEMO orders are returned.
Demo Driver loads prospects	Eligible unassigned DEMO orders are returned.
Regular agent accepts a DEMO order by ID	Request is rejected.
Delivery partner assigns a regular agent to a DEMO order	Request is rejected with DEMO merchant orders can only be assigned to Demo Driver.
Delivery partner assigns Demo Driver	Assignment follows the normal payment-type and workload checks.
Regular agent is online when a new DEMO order is created	No prospect notification is sent to that agent.
Demo Driver is online when a new DEMO order is created	Demo Driver may receive the prospect notification.
A normal merchant creates an order	Existing assignment and prospect behavior is unchanged.

After testing, verify there are no active DEMO B2C or B2B records whose agentId belongs to another agent.

Closed integration lifecycle

Use the Demo Merchant's pk_live_ key. These requests follow normal production behavior, including wallet checks, notifications, webhooks, and dispatch. Coordinate the test window with Demo Delivery Partner operations and ensure Demo Driver is available before creating an order.

Minimum lifecycle check:

1. Create a customer and order using the Demo Merchant's pk_live_ key.
2. Assign or accept the order through the Demo Delivery Partner and Demo Driver workflows.
3. Complete picked_up, in_transit, and delivered in the agent app.
4. Confirm the status history and public tracking response.
5. Confirm the order is visible to Demo Merchant and Demo Delivery Partner users but absent from regular-agent prospects.

Merchant order count

The /merchant/orders table and the B2C Orders navigation badge intentionally show different measures:

• The table total includes all visible orders matching the selected filters, including terminal statuses.
• The badge counts active orders in pending, assigned, or in_transit.

When testing, compare the badge only with those active statuses and clear any table filters first.

Permission-aware merchant navigation

Test both merchant_admin and branch_manager accounts on desktop and mobile navigation:

• Admin-only Management items appear only for merchant administrators.
• Hidden groups do not leave orphaned or doubled horizontal separators.
• B2B and Wallet visibility still follows the merchant feature flags.

reCAPTCHA badge lifecycle

The Admin, Merchant, Delivery Partner, and Customer SPAs load reCAPTCHA only when an OTP or login action executes.

For each SPA:

1. Open its login page and submit the first authentication action.
2. Confirm the reCAPTCHA badge can appear while verification is active.
3. Complete login and confirm the bottom-right badge becomes hidden.
4. Sign out and retry authentication; confirm verification still executes and the badge can become visible again.
5. Confirm failed verification leaves the user on the login page with the existing security error.

Hiding the badge after authentication is visual only. It does not disable token generation for a later authentication action.

Merchant Business Profile

/merchant/profile represents the merchant business, not the signed-in person's account.

Verify with a merchant administrator:

• The identity card shows the logo, names, code, localized business type, commercial license, and scheduled-order capability.
• Identity fields are presented as Wasal-managed information rather than editable disabled inputs.
• Public phone, email, website, description, and social channels remain editable.
• Validation errors remain attached to the relevant phone or email field.
• English and Arabic labels use Business Profile / ملف النشاط التجاري.

A signed-in user's personal name, login email, phone, role, and branch belong to the merchant-user account and must not be presented as business-profile fields.