​

Cello Integration QA Checklist

​

Purpose

This document provides a comprehensive checklist for testing and verifying the Cello referral system integration. Use this to ensure all features have been properly implemented according to the acceptance criteria defined in the React + Node.js Integration Guide.

​

How to Use This Checklist

• Check off each item as you verify it works correctly
• Phase 1 items are mandatory for Cello to function
• Phase 2 items are optional enhancements but highly recommended
• Refer to the Integration Guide for implementation details and troubleshooting
• Test in both sandbox and production environments where applicable

---

​

Step 1: Server-Side Helpers

​

Acceptance Criteria

• createCelloJwt() generates a valid HS512 JWT with productId, productUserId, iat claims only
• getCelloScriptUrl() returns correct URL based on environment
• buildCelloBootConfig() returns config with productUserDetails including firstName, lastName, fullName, email
• No sensitive data (product secret) is exposed to the client

---

​

Step 2: Referral Widget (Authenticated Users)

​

Phase 1 - Basic Widget Functionality (Mandatory)

• Token endpoint returns { enabled: true, bootConfig: {...} } for authenticated users
• Token endpoint returns { enabled: false } for unauthenticated users
• Cello script loads without CORS errors in browser Network tab
• Console shows no “User is not authorized” errors
• Widget opens when clicking the launcher button
• Notification badges appear on the launcher (test with your own referral link)

​

Phase 1 - Custom Launcher with Dynamic Labels (REQUIRED If Using Custom Launcher)

• Dynamic reward label displays on launcher (e.g., “Earn €1000” not just “Earn”)
• Label updates within 1-2 seconds on FIRST LOGIN (test with fresh session, not just page refresh)
• Browser console shows successful getLabels call
• Launcher degrades gracefully if labels fail to load (shows fallback text e.g. “Invite & Earn”)
• Labels persist correctly during navigation within SPA (don’t require page refresh)

​

Phase 2 - Enhanced Error Handling & Loading States (Optional but Recommended)

• Widget boot errors are logged with detailed information
• Failed API calls include request/response details in logs
• Retry logic attempts boot up to 3 times on failure
• Attribution errors don’t block page load or form submission
• Launcher shows loading state while fetching labels (visual feedback)
• User sees appropriate feedback for connection issues (if implementing UI indicators)

---

​

Step 3: Public Attribution

​

Phase 1 - Core Attribution (Mandatory)

• Attribution script loads on public pages (check Network tab)
• window.CelloAttribution function is available after script loads
• Visiting /?ucc=TEST123 stores the referral code
• useCelloAttribution() hook returns the stored UCC
• Referrer name displays on signup page when visiting via referral link

​

Phase 2 - Enhanced Attribution (Optional)

• Hook returns error states for debugging
• Referrer name displays on signup page when visiting via referral link
• Campaign configuration fetched alongside UCC and referrer name
• Campaign discount displays correctly on signup page (e.g., “30% off your first 3 months”)
• Signup banner shows only referrer name when no discount is configured (social proof)
• Discount format adjusts for singular vs plural months (“month” vs “months”)
• Timeout errors are non-blocking and logged clearly
• Attribution failures don’t crash the page

---

​

Step 4: Signup Event Tracking

​

Phase 1 - Core Event Tracking (Mandatory)

• fetchCelloAccessToken() successfully retrieves and caches access token
• Signup with referral code triggers emitReferralUpdatedEvent()
• Server logs show POST /events returning status 200
• Cello dashboard shows the new signup event
• User model stores referralCode field
• Signup without referral code works normally (no errors)

​

Phase 2 - Referral Code Validation (Optional but Recommended)

• validateReferralCode() successfully validates valid referral codes (returns true or valid object)
• validateReferralCode() correctly identifies invalid codes (returns false or invalid object)
• Invalid referral codes are NOT stored in user model
• Invalid referral codes do NOT trigger emitReferralUpdatedEvent()
• Signup completes successfully even with invalid referral codes (non-blocking)
• Campaign ID is stored alongside referral code when available (enhanced implementation)

​

Phase 2 - Enhanced Logging (Optional but Recommended)

• Token request logs include full URL and response details
• Event emission logs include payload structure
• Environment variables validated on startup
• Failed API calls show detailed error context

---

​

Step 5: Stripe Integration

​

Acceptance Criteria

• Stripe customers have cello_ucc and new_user_id in metadata
• Stripe webhook configured in Cello portal
• Test purchase shows in Cello dashboard with correct attribution
• Reading user data like referral_code from edge functions is working correctly

---

​

Testing Notes

​

Environment Checklist

• All required environment variables are set (see Integration Guide Prerequisites)
• Cello Portal is properly configured with product ID and API keys
• Testing in correct environment (sandbox vs production)

​

Common Test Scenarios

​

1. New User via Referral Link

1. Visit site with ?ucc=TEST123 parameter
2. Complete signup flow
3. Verify referral code is stored
4. Check Cello dashboard for signup event

​

2. Authenticated User Referral Widget

1. Login as existing user
2. Click referral launcher button
3. Verify widget opens with user’s referral link
4. Copy link and test in incognito mode

​

3. Dynamic Labels on First Login (if using custom launcher)

1. Clear browser session/cookies (fresh state)
2. Login as existing user
3. CRITICAL: Verify dynamic label appears within 1-2 seconds (e.g., “Earn €1000”)
4. Do NOT refresh the page - labels must appear on first render
5. Navigate to different pages within the app
6. Verify labels persist without requiring page refresh
7. Check browser console for successful getLabels call

​

4. Invalid Referral Code (Phase 2 - if validation implemented)

1. Visit site with ?ucc=INVALID123 parameter
2. Complete signup flow
3. Verify user is created successfully
4. Verify invalid code is NOT stored in database
5. Verify no event sent to Cello dashboard

​

5. Stripe Purchase Attribution

1. Complete purchase as referred user
2. Verify Stripe customer has correct metadata
3. Check Cello dashboard for commission tracking

​

Troubleshooting

If any checklist item fails, refer to the “Troubleshooting” section in the Integration Guide for detailed debugging steps.

---

​

Sign-off

• All Phase 1 (Mandatory) items verified and passing
• Tested in sandbox environment
• Tested in production environment (when ready)
• All critical user flows tested end-to-end

Notes:

---