Testing Guide for Draw Winner Reveal Feature

This guide provides step-by-step instructions for testing the draw winner reveal functionality.

Prerequisites

1. Start the application using docker-compose:

   docker-compose up -d
   

   Note: The database schema (api/common/infra/database/schema/public.sql) already includes the revealed status and reveal_at column. No additional migrations are needed for fresh installations.

Test Scenarios

1. Create and Complete a Draw with Reveal Date

1. Create a Draw

   • Navigate to the admin panel at http://localhost:3000
   • Go to Draws section
   • Create a new draw with an asset
   • Activate the draw

2. Select a Winner

   • Wait for all tickets to be sold (or mark tickets as sold manually in the database)
   • The cron job will automatically select a winner
   • Or manually trigger winner selection via POST /admin/draws/:id/select

3. Complete Draw with Reveal Date

   • In the admin panel, for a draw with status "selected"
   • Click the dropdown menu and select "Complete"
   • In the dialog, enter a future date/time for the reveal
   • Click "Complete"
   • Verify that the draw status changes to "completed"

4. View Winner Details (Admin)

   • For completed or selected draws, click "View Winner" button
   • Verify that winner details (name, email, ticket ID, DOB) are displayed

5. Test Mobile API - Before Reveal

   • Call GET /mobile/draws/:id/winner for a completed draw (before reveal time)
   • Verify that the API returns a 403 Forbidden error
   • Call GET /mobile/draws/:id for a completed draw
   • Verify that the response includes reveal_at field with the scheduled reveal time

6. Wait for Reveal Time

   • Wait until the reveal time has passed
   • The cron job (runs every minute) will automatically transition the draw to "revealed"

7. Test Mobile API - After Reveal

   • Call GET /mobile/draws/:id/winner for a revealed draw
   • Verify that the API returns winner details including ticket ID
   • Call GET /mobile/draws/:id
   • Verify that the response includes winner_ticket_id field

2. API Endpoints to Test

Admin Endpoints

• PUT /admin/draws/:id/status - Complete draw with reveal date

  {
    "action": "complete",
    "reveal_at": "2026-02-25T10:00:00Z"
  }
  

• GET /admin/draws/:id/winner - Get winner details (admin only) Response:

  {
    "id": 1,
    "key": "user_key",
    "name": "John Doe",
    "dateOfBirth": "1990-01-01T00:00:00Z",
    "email": "user@example.com",
    "ticketId": 123
  }
  

Mobile Endpoints

• GET /mobile/draws/:id - Get draw details

  • For completed draws: includes reveal_at
  • For revealed draws: includes winner_ticket_id

• GET /mobile/draws/:id/winner - Get winner (only for revealed draws)

  • Returns 403 if not revealed
  • Returns winner details if revealed

3. Cron Jobs

The following cron jobs handle automatic status transitions:

1. Winner Selection (runs every minute in dev, every hour in staging)

   • Automatically selects winners for active draws with all tickets sold
   • Transitions draws from "active" to "selected"

2. Winner Reveal (runs every minute)

   • Automatically reveals winners for completed draws past their reveal time
   • Transitions draws from "completed" to "revealed"

4. Database Verification

-- Check draw statuses
SELECT id, status, reveal_at FROM public.draws;

-- Check if revealed status is available
SELECT unnest(enum_range(NULL::draw_status))::text;

-- Manually update a draw for testing
UPDATE public.draws SET reveal_at = NOW() - INTERVAL '1 minute' WHERE id = 1;

Expected Behavior

1. Admin Flow:

   • Admin can complete a draw by specifying a reveal date/time
   • Admin can view winner details immediately after winner selection
   • Draw shows "revealed" status after the reveal time passes

2. Mobile Flow:

   • Mobile users see the reveal countdown for completed draws
   • Mobile users can only see the winning ticket number after reveal
   • Mobile users get a 403 error if they try to access winner details before reveal

3. Automatic Transitions:

   • Draws transition to "selected" when all tickets are sold
   • Draws transition to "revealed" when reveal time passes