Skip to content

Testing Guide

This guide walks you through setting up and testing all functionalities of the Diskover digital storefront platform by manually navigating the website and using the features.

Prerequisites

Before starting, ensure you have: 1. Completed the Clerk Setup with valid API keys 2. Started the application with make dev 3. Frontend running at http://localhost:5173 4. Backend API running at http://localhost:8080

Table of Contents

  1. User Registration & Authentication
  2. Browse Products (Public)
  3. Personal Organization Setup
  4. Create & Sell Products
  5. Purchase Digital Products
  6. Purchase Memberships
  7. View Purchases & Entitlements
  8. Organization Management
  9. System Administration
  10. API Testing

1. User Registration & Authentication

Test Registration Flow

Purpose: Create a new user account and verify authentication works properly.

Steps: 1. Navigate to http://localhost:5173 2. Click "Sign Up" or "Register" in the header 3. Fill in registration form: - Email address (e.g., testuser@example.com) - Password (meet Clerk's requirements) - Full name 4. Click "Create Account" 5. Verify email if Clerk requires it (check email inbox)

Expected Results: - ✅ User is redirected to /dashboard after registration - ✅ User's name appears in the dashboard header - ✅ A new user record is created in the database - ✅ A personal organization is automatically created for the user

What's Tested: - Clerk authentication integration - User creation in database - Automatic personal organization creation - Session management

Test Login Flow

Purpose: Verify existing users can log in successfully.

Steps: 1. Log out if currently logged in 2. Navigate to http://localhost:5173/login 3. Enter your credentials 4. Click "Sign In"

Expected Results: - ✅ User is redirected to /dashboard - ✅ Authentication token is stored - ✅ User can access protected routes

What's Tested: - Clerk login integration - Session persistence - Protected route access

2. Browse Products (Public)

Test Product Listing

Purpose: Verify anyone can browse available products without authentication.

Steps: 1. Log out (if logged in) 2. Navigate to http://localhost:5173 3. View the product list on the homepage

Expected Results: - ✅ Products are displayed in a grid/list format - ✅ Each product shows: name, description, price, type (digital/membership) - ✅ Only active products are shown - ✅ Products from all organizations are visible

What's Tested: - Public product listing API (GET /products) - Product filtering (active products only) - Product display components

Test Product Details

Purpose: View detailed information about a specific product.

Steps: 1. From the product list, click on any product 2. Review the product detail page

Expected Results: - ✅ Product name, full description, and price are displayed - ✅ Product type (Digital Product or Membership) is shown - ✅ For memberships: subscription duration is displayed - ✅ Seller/organization information is visible - ✅ "Purchase" or "Add to Cart" button is present

What's Tested: - Product detail API (GET /products/{id}) - Product information rendering - Membership-specific fields display

3. Personal Organization Setup

Test Personal Organization

Purpose: Verify each user has a personal organization for selling products.

Steps: 1. Log in to your account 2. Navigate to /dashboard/orgs 3. Locate your personal organization (marked as "Personal")

Expected Results: - ✅ Personal organization exists with your user ID in the slug - ✅ You are listed as the owner of this organization - ✅ Organization name matches your user name - ✅ is_personal flag is set to true

What's Tested: - Automatic personal org creation during registration - Organization ownership - Personal org identification

4. Create & Sell Products

Test Create Digital Product

Purpose: Create a digital product for sale.

Steps: 1. Log in and go to /dashboard/selling 2. Click "Create Product" or "Add New Product" 3. Fill in the product form: - Name: "My First eBook" - Description: "A comprehensive guide to..." - Type: Select "Digital Product" - Price: 2999 (displayed as $29.99) - Leave subscription days empty (not applicable for digital products) 4. (Optional) Upload associated files/assets 5. Click "Create" or "Publish"

Expected Results: - ✅ Product is created and visible in "My Products" list - ✅ Product is set to active by default - ✅ Product belongs to your personal organization - ✅ Product appears in public product listing - ✅ subscription_days is NULL for digital products

What's Tested: - Product creation API (POST /products) - Digital product validation - Product ownership - Public product visibility

Test Create Membership Product

Purpose: Create a membership/subscription product.

Steps: 1. From /dashboard/selling, click "Create Product" 2. Fill in the product form: - Name: "Premium Membership" - Description: "Get access to all exclusive content" - Type: Select "Membership" - Price: 1999 (displayed as $19.99) - Subscription Days: 30 (monthly membership) 3. Click "Create"

Expected Results: - ✅ Membership product is created successfully - ✅ subscription_days is set to 30 - ✅ Product type is set to "membership" - ✅ Validation ensures subscription_days is required for memberships

What's Tested: - Membership product creation - Subscription duration field validation - Product type constraints

Test Product Management

Purpose: Update and manage existing products.

Steps: 1. Go to /dashboard/selling 2. Select one of your products 3. Click "Edit" or similar action 4. Update product details (name, description, price) 5. Test deactivating the product (toggle "Active" status) 6. Save changes

Expected Results: - ✅ Product details are updated successfully - ✅ Deactivated products don't appear in public listing - ✅ Deactivated products still visible in your seller dashboard - ✅ Price changes are reflected immediately

What's Tested: - Product update API - Product activation/deactivation - Active product filtering

5. Purchase Digital Products

Test Digital Product Purchase

Purpose: Complete a purchase transaction for a digital product.

Steps: 1. Log in as a different user (or create a second test account) 2. Browse products and select a digital product (not your own) 3. Click "Purchase" or "Buy Now" 4. Review order summary in checkout page (/checkout) 5. Confirm purchase (payment processing may be simulated)

Expected Results: - ✅ Transaction is created with status "completed" - ✅ User receives entitlement to download/access the product - ✅ Transaction appears in user's purchase history (/dashboard/purchases) - ✅ Seller sees the transaction in their sales records - ✅ Entitlement has no expiration date (expires_at is NULL)

What's Tested: - Transaction creation API (POST /transactions) - Entitlement generation - Digital product fulfillment - Purchase history tracking

Test Multiple Product Purchase

Purpose: Purchase multiple products in a single transaction.

Steps: 1. Add multiple products to cart (if cart functionality exists) 2. Proceed to checkout 3. Complete purchase

Expected Results: - ✅ Separate transaction records for each product (or single transaction with line items) - ✅ Entitlements created for all purchased products - ✅ Total price calculated correctly

What's Tested: - Cart functionality - Multiple product transactions - Entitlement batch creation

6. Purchase Memberships

Test Membership Purchase

Purpose: Purchase a membership product and verify subscription creation.

Steps: 1. Log in as a user (not the product owner) 2. Browse and select a membership product 3. Review subscription details (duration, billing cycle) 4. Complete purchase

Expected Results: - ✅ Transaction is created with status "completed" - ✅ Subscription record is created with: - status: "active" - current_period_start: Today's date - current_period_end: Today + subscription_days - ✅ Entitlements are created for all assets linked to the membership - ✅ Entitlement expiration matches subscription period end

What's Tested: - Membership transaction processing - Subscription creation - Subscription period calculation - Time-based entitlements

Test Subscription Management

Purpose: View and manage active subscriptions.

Steps: 1. Go to /dashboard/purchases 2. Locate your active memberships section 3. View subscription details: - Current period start/end dates - Status (active, past_due, canceled, expired) - Auto-renewal information

Expected Results: - ✅ Active subscriptions are displayed - ✅ Period dates are accurate - ✅ Status is clearly indicated

What's Tested: - Subscription listing - Subscription status display - Period tracking

7. View Purchases & Entitlements

Test Purchase History

Purpose: View all past purchases and their details.

Steps: 1. Log in and navigate to /dashboard/purchases 2. Review the list of all your purchases

Expected Results: - ✅ All completed transactions are listed - ✅ Each transaction shows: - Product name - Purchase date - Amount paid - Transaction status - ✅ Transactions are sorted by date (newest first)

What's Tested: - Transaction history API (GET /transactions) - User-specific transaction filtering - Transaction data display

Test Access to Purchased Content

Purpose: Verify users can access content they've purchased.

Steps: 1. From /dashboard/purchases, click on a purchased product 2. Look for download/access buttons or links 3. Attempt to download or access the product content

Expected Results: - ✅ User can see download links for purchased products - ✅ Access is granted only if entitlement exists and is not expired - ✅ Download URLs are generated (presigned URLs if using S3) - ✅ Unauthorized users cannot access the content

What's Tested: - Entitlement validation - Content access control - Download URL generation (if S3 is configured)

Test Expired Entitlements

Purpose: Verify access is revoked when memberships expire.

Steps: 1. Purchase a short-term membership (or manually update DB for testing) 2. Wait for the subscription period to end (or manually expire it) 3. Attempt to access the membership content

Expected Results: - ✅ Access is denied after expiration - ✅ Subscription status changes to "expired" - ✅ User is prompted to renew

What's Tested: - Entitlement expiration logic - Subscription expiration handling - Access revocation

8. Organization Management

Test Create Shared Organization

Purpose: Create a team/company organization separate from personal org.

Steps: 1. Log in and go to /dashboard/orgs 2. Click "Create Organization" 3. Fill in organization details: - Name: "My Company LLC" - Slug: "my-company" (URL-friendly identifier) 4. Click "Create"

Expected Results: - ✅ New organization is created with is_personal = false - ✅ You are automatically added as the owner - ✅ Organization appears in your organizations list - ✅ Products can be created under this organization

What's Tested: - Organization creation API (POST /orgs) - Organization ownership assignment - Shared organization functionality

Test Add Organization Members

Purpose: Invite other users to join your organization.

Steps: 1. Navigate to /dashboard/orgs/{org-id} 2. Go to the Members tab 3. Click "Add Member" 4. Enter user email or ID 5. Assign role (owner, admin, member, viewer) 6. Send invitation

Expected Results: - ✅ Member is added to organization - ✅ Member can see organization in their orgs list - ✅ Member's permissions match assigned role - ✅ Members can collaborate on products (depending on role)

What's Tested: - Organization member management API (POST /orgs/{id}/members) - Role-based access control - Multi-user organization support

Test Organization Roles

Purpose: Verify different roles have appropriate permissions.

Roles: - Owner: Full control, can delete org, manage all members - Admin: Manage products and members, cannot delete org - Member: Create/edit products, view members - Viewer: Read-only access

Steps: 1. Add members with different roles 2. Log in as each member type 3. Test permissions (create product, edit org, etc.)

Expected Results: - ✅ Permissions are enforced correctly - ✅ Unauthorized actions are blocked - ✅ UI reflects available actions based on role

What's Tested: - Role-based authorization - Permission enforcement - UI permission rendering

9. System Administration

Test Admin Dashboard Access

Purpose: Verify system admins can access administrative features.

Prerequisites: - User must be added to system_admins table in database - Or register with an admin-authorized email

Steps: 1. Log in as a system admin user 2. Navigate to /goose (admin panel) 3. Review admin dashboard

Expected Results: - ✅ Admin dashboard is accessible - ✅ Non-admin users are redirected or see "Forbidden" error - ✅ Admin can view system-wide data

What's Tested: - System admin role detection - Admin route protection - Admin authentication

Test Transaction Reconciliation

Purpose: System admins can reconcile payment transactions.

Steps: 1. As admin, go to /goose/reconciliation 2. View list of all transactions 3. Find a "pending" transaction 4. Click "Reconcile" or similar action 5. Update transaction status (mark as completed, failed, refunded)

Expected Results: - ✅ Admin can view all user transactions - ✅ Transaction status can be updated - ✅ Status changes are reflected in user's purchase history - ✅ Audit trail is maintained

What's Tested: - Admin transaction management API (POST /admin/transactions/{id}/reconcile) - Transaction status updates - System-wide transaction visibility

Test View All System Data

Purpose: Admins can view aggregated system data.

Steps: 1. Navigate to /goose/view-all 2. Review system statistics: - Total users - Total products - Total transactions - Revenue metrics

Expected Results: - ✅ All data is visible to admin - ✅ Aggregated statistics are accurate - ✅ Data is properly formatted

What's Tested: - Admin analytics APIs (GET /admin/users, GET /admin/orgs, GET /admin/products) - Data aggregation - System-wide reporting

10. API Testing

Test with Bruno or Postman

Purpose: Test API endpoints directly without the UI.

Setup: 1. API collection is available in api/diskover-requests/ 2. Import into Bruno (recommended) or Postman 3. Configure environment variables: - BASE_URL: http://localhost:8080 - AUTH_TOKEN: Get from Clerk session

Health Check

Endpoint: GET /health

Expected Response: 

{
  "status": "ok",
  "database": "connected"
}

What's Tested: Backend and database connectivity

List Products

Endpoint: GET /products

Query Parameters: - type: "digital" or "membership" (optional) - org_id: Filter by organization (optional)

Expected Response: 

[
  {
    "id": "uuid",
    "name": "Product Name",
    "description": "Product description",
    "type": "digital",
    "price": 2999,
    "is_active": true,
    "org_id": "uuid",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

What's Tested: Product listing API

Get Product by ID

Endpoint: GET /products/{id}

Expected Response: 

{
  "id": "uuid",
  "name": "Product Name",
  "description": "Full description",
  "type": "membership",
  "price": 1999,
  "subscription_days": 30,
  "is_active": true,
  "org_id": "uuid",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

What's Tested: Single product retrieval

Create Transaction

Endpoint: POST /transactions

Authentication: Required (Bearer token)

Request Body: 

{
  "product_id": "uuid",
  "payment_method": "credit_card"
}

Expected Response: 

{
  "id": "uuid",
  "user_id": "uuid",
  "product_id": "uuid",
  "amount": 2999,
  "currency": "USD",
  "status": "completed",
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:00:00Z"
}

What's Tested: Transaction creation, payment processing

Get User Profile

Endpoint: GET /users/me

Authentication: Required

Expected Response: 

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "Test User",
  "personal_org_id": "uuid",
  "created_at": "2024-01-01T00:00:00Z"
}

What's Tested: User profile retrieval, authentication

List User Transactions

Endpoint: GET /transactions

Authentication: Required

Expected Response: 

[
  {
    "id": "uuid",
    "product_id": "uuid",
    "amount": 2999,
    "currency": "USD",
    "status": "completed",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

What's Tested: User transaction history

Admin: List All Transactions

Endpoint: GET /admin/transactions

Authentication: Required (System Admin)

Expected Response: Array of all transactions in the system

What's Tested: Admin access, system-wide data retrieval

Admin: Reconcile Transaction

Endpoint: POST /admin/transactions/{id}/reconcile

Authentication: Required (System Admin)

Request Body: 

{
  "status": "completed",
  "external_payment_id": "stripe_abc123"
}

Expected Response: 

{
  "id": "uuid",
  "status": "completed",
  "external_payment_id": "stripe_abc123"
}

What's Tested: Transaction reconciliation, admin permissions

Testing Checklist

Core Functionality

  • [ ] User registration works
  • [ ] User login works
  • [ ] Browse products (unauthenticated)
  • [ ] View product details
  • [ ] Create digital product
  • [ ] Create membership product
  • [ ] Edit/update product
  • [ ] Deactivate product
  • [ ] Purchase digital product
  • [ ] Purchase membership
  • [ ] View purchase history
  • [ ] Access purchased content
  • [ ] Verify entitlements

Organization Features

  • [ ] Personal org exists after registration
  • [ ] Create shared organization
  • [ ] Add organization members
  • [ ] Test different member roles
  • [ ] Products belong to correct org

Subscription Features

  • [ ] Subscription created on membership purchase
  • [ ] Subscription period calculated correctly
  • [ ] Active subscription status
  • [ ] Subscription expiration (if testable)

Admin Features

  • [ ] Admin dashboard access (admin users only)
  • [ ] View all transactions
  • [ ] Reconcile transactions
  • [ ] View system statistics
  • [ ] Non-admins blocked from admin routes

API Testing

  • [ ] Health check endpoint
  • [ ] Product listing API
  • [ ] Product detail API
  • [ ] Transaction creation API
  • [ ] User profile API
  • [ ] Admin APIs (with admin auth)

Common Issues & Troubleshooting

Issue: Blank page after login

Cause: Clerk keys not configured properly
Solution: Check frontend/.env has valid VITE_CLERK_PUBLISHABLE_KEY

Issue: 401 Unauthorized on API calls

Cause: Authentication token not sent or invalid
Solution: - Ensure user is logged in - Check backend has valid CLERK_SECRET_KEY in root .env - Clear browser cookies and log in again

Issue: Products not appearing

Cause: Products may be inactive or database empty
Solution: - Check product is_active status is true - Verify products exist in database - Check console for API errors

Issue: Cannot create product

Cause: Not a member of any organization
Solution: - Verify personal organization was created during registration - Check org_members table for user membership

Issue: Admin routes not accessible

Cause: User not in system_admins table
Solution: Manually add user to system_admins: 

INSERT INTO system_admins (user_id, permissions)
VALUES ('user-uuid-here', '{"read": true, "write": true}');

Issue: Transaction fails

Cause: Payment processing not configured
Solution: - Check backend logs for errors - Verify transaction status in database - Payment integration may need configuration

Database Inspection (For Debugging)

Connect to PostgreSQL

docker-compose exec postgres psql -U diskover -d diskover

Useful Queries

View all users: 

SELECT id, email, name, clerk_id, created_at FROM users;

View all products: 

SELECT id, name, type, price, is_active, org_id FROM products;

View all transactions: 

SELECT id, user_id, product_id, amount, status, created_at FROM transactions;

View user's entitlements: 

SELECT e.id, e.user_id, p.name as product, e.expires_at 
FROM entitlements e
JOIN products p ON e.product_id = p.id
WHERE e.user_id = 'user-uuid-here';

View subscriptions: 

SELECT id, user_id, product_id, status, current_period_end 
FROM subscriptions 
WHERE status = 'active';

View system admins: 

SELECT sa.id, u.email, u.name, sa.permissions 
FROM system_admins sa
JOIN users u ON sa.user_id = u.id;

Next Steps

After completing this testing guide:

  1. Report Issues: Document any bugs or unexpected behavior
  2. Extend Tests: Add automated tests for critical flows
  3. Performance Testing: Test with larger datasets
  4. Security Testing: Verify authentication and authorization edge cases
  5. Integration Testing: Test with real payment providers (if applicable)

Additional Resources

Happy Testing! 🚀