> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Test User Cleanup and Staging Verification Guide

> Before deleting anything, identify what will be deleted:

**Date:** 2026-01-20\
**Purpose:** Guide for cleaning up test users from production and verifying staging environment

***

## Overview

This guide covers:

1. **Removing test users from production** - Safe cleanup procedures
2. **Checking staging status** - Verification of staging environment
3. **Testing strategy** - Whether tests should run in staging

***

## Part 1: Clean Up Test Users from Production

### ⚠️ Important Warnings

* **Test users should NOT exist in production** - Only real user signups belong there
* **Deletion is permanent** - Always run dry-run first
* **Verify environment** - Double-check you're connected to production before deleting
* **Backup first** - Consider exporting user data before deletion (if needed)

### Step 1: Identify Test Users (Dry-Run)

**Before deleting anything, identify what will be deleted:**

```bash theme={null}
# Dry-run to see test users in production
npx tsx scripts/database/cleanup-test-users.ts --dry-run --env production
```

**Expected Output:**

* Lists all test users that match patterns
* Shows breakdown by type (E2E, RLS, debug, etc.)
* Shows recent test users
* **No users are deleted** in dry-run mode

### Step 2: Verify Environment

**Double-check you're connected to production:**

```bash theme={null}
# Check Supabase connection
npx supabase status

# Should show production project details
```

**⚠️ CRITICAL:** If you see a different project ID, STOP. You're not connected to production.

### Step 3: Preview Deletion

**See what would be deleted without actually deleting:**

```bash theme={null}
# Preview mode (no --confirm flag)
npx tsx scripts/database/cleanup-test-users.ts --env production
```

This shows:

* Total test users found
* Breakdown by type
* Recent test users
* **No deletion occurs** - you must add `--confirm` to actually delete

### Step 4: Delete Test Users (Production Only)

**⚠️ ONLY run this in production after verifying the preview:**

```bash theme={null}
# Actually delete test users (requires --confirm flag)
npx tsx scripts/database/cleanup-test-users.ts --env production --confirm
```

**What happens:**

1. Script shows 5-second warning
2. Identifies all test users matching patterns:
   * `%test%` - Contains "test"
   * `%example%` - Contains "example"
   * `e2e-%` - E2E test users
   * `rls-%` - RLS test users
   * `%debug%` - Debug users
   * `%staging%` - Staging seed users
3. Deletes users in batches (10 at a time)
4. Shows progress and final count

**After deletion:**

* Test users are permanently removed
* Associated profiles may be cleaned up by triggers
* Production should only have real user signups

***

## Part 2: Check Staging Status

### Verify Staging Environment

**Check staging database status:**

```bash theme={null}
# Check staging status
npx tsx scripts/database/check-staging-status.ts
```

**What it checks:**

1. ✅ **Database Connection** - Can connect to staging
2. ✅ **Test Users Count** - Test users present (expected in staging)
3. ✅ **Seed Data** - Seed organizations and users exist
4. ✅ **Environment Isolation** - No production data leaked

**Expected Results for Staging:**

* ✅ Connection successful
* ✅ Test users found (this is expected in staging)
* ✅ Seed data present (organizations with `00000000-` prefix)
* ✅ No production data detected

### Manual Staging Verification

**Check staging via Supabase Dashboard:**

1. **Go to Supabase Dashboard:**
   * Navigate to staging project: `bcuftbeczbudndukafbc`
   * Or switch to staging branch if using branching

2. **Verify Test Data:**

   ```sql theme={null}
   -- Check seed organizations
   SELECT COUNT(*) FROM pf_organizations 
   WHERE id LIKE '00000000-%';
   -- Expected: > 0 (seed data should exist)

   -- Check test users
   SELECT COUNT(*) FROM auth.users 
   WHERE email LIKE '%test%' OR email LIKE '%example%';
   -- Expected: > 0 (test users are normal in staging)
   ```

3. **Verify Isolation:**

   ```sql theme={null}
   -- Check for production data (should be 0)
   SELECT COUNT(*) FROM pf_organizations 
   WHERE id NOT LIKE '00000000-%';
   -- Expected: 0 (no production data in staging)
   ```

***

## Part 3: Should Tests Run in Staging?

### Current Testing Strategy

**Current Setup:**

* Tests run in GitHub Actions CI/CD
* Uses production Supabase project (configured via environment variables)
* RLS tests require service role key (bypasses RLS)
* Tests create temporary test users during runs

### Recommendation: Use Staging for Tests

**✅ YES - Tests should run in staging, not production**

**Reasons:**

1. **Data Isolation** - Test users won't pollute production
2. **Safety** - No risk of affecting real users
3. **Seed Data** - Staging has predictable test data
4. **Performance** - Staging can handle test load without affecting production
5. **Cleanup** - Test users in staging are expected and acceptable

### How to Configure Tests for Staging

**Option 1: Use Staging Secrets in GitHub Actions**

Update `.github/workflows/tests.yml`:

```yaml theme={null}
env:
  VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL_STAGING }}
  SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY_STAGING }}
  VITE_SUPABASE_PUBLISHABLE_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_KEY_STAGING }}
```

**Option 2: Environment-Specific Test Jobs**

Create separate test jobs for staging and production:

```yaml theme={null}
rls-tests-staging:
  name: RLS Tests (Staging)
  env:
    VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL_STAGING }}
    SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY_STAGING }}
  # ... test steps

rls-tests-production:
  name: RLS Tests (Production) - Read Only
  if: github.ref == 'refs/heads/main'
  env:
    VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL }}
    SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
  # ... read-only validation tests
```

### Test User Cleanup in Staging

**Staging test users are expected and acceptable:**

* Test users created during CI/CD runs are normal
* Periodic cleanup (30+ days old) is optional
* Seed data users should remain

**Optional: Periodic Cleanup Script**

```bash theme={null}
# Clean up old test users in staging (optional)
npx tsx scripts/database/cleanup-test-users.ts \
  --env staging \
  --dry-run \
  --older-than 30  # days (if implemented)
```

***

## Summary

### Production

* ✅ **Remove all test users** - Use cleanup script
* ✅ **Only real user signups** - No test data
* ✅ **Regular cleanup** - Monitor for accidental test users

### Staging

* ✅ **Test users are expected** - Normal and acceptable
* ✅ **Seed data should exist** - For UAT testing
* ✅ **Use for CI/CD tests** - Recommended over production
* ⚠️ **Optional cleanup** - Only very old test users (30+ days)

### Testing Strategy

* ✅ **Run tests in staging** - Not production
* ✅ **Use staging secrets** - Separate from production
* ✅ **Test users in staging** - Expected and acceptable
* ❌ **No test users in production** - Clean up immediately

***

## Related Documentation

* **User Management Guide:** `docs/development/USER_MANAGEMENT_AND_CLEANUP.md`
* **Testing Guide:** `docs/testing/TESTING_SETUP_AND_RUN.md`
* **Staging Setup:** `docs/development/SUPABASE_MULTI_ENV_SETUP.md`
* **Verification Guide:** `docs/development/VERIFICATION_TESTING_GUIDE.md`

***

## Quick Reference Commands

```bash theme={null}
# Production: Identify test users (dry-run)
npx tsx scripts/database/cleanup-test-users.ts --dry-run --env production

# Production: Preview deletion
npx tsx scripts/database/cleanup-test-users.ts --env production

# Production: Actually delete (CAREFUL!)
npx tsx scripts/database/cleanup-test-users.ts --env production --confirm

# Staging: Check status
npx tsx scripts/database/check-staging-status.ts

# Staging: Check test users (optional)
npx tsx scripts/database/cleanup-test-users.ts --dry-run --env staging
```