feat: add new E2E test command and update tests README

- Introduced a new command in package.json for running end-to-end tests: `test:e2e`.
- Updated the tests README to provide a comprehensive overview of included tests and their execution instructions.
- Consolidated authentication test details and added notes on the new E2E flow for better clarity and usability.

Author: regenrek

package.json

@@ -16,6 +16,7 @@
     "test": "vitest",
     "test:auth": "vitest tests/auth-integration.test.ts",
     "test:auth:watch": "vitest tests/auth-integration.test.ts --watch",
+    "test:e2e": "vitest tests/e2e-auth-billing.test.ts",
     "db:pull": "npx drizzle-kit pull",
     "db:generate": "npx drizzle-kit generate",
     "db:migrate": "npx drizzle-kit migrate",

tests/README.md

@@ -1,100 +1,42 @@
-# Authentication Tests
+# Tests
 
-This directory contains end-to-end tests for the authentication system.
+## What's included
 
-## Running Tests
+- `auth-integration.test.ts` — basic Better‑Auth HTTP integration tests
+- `email-security.test.ts` — email provider security/log redaction tests
+- `e2e-auth-billing.test.ts` — **new** end‑to‑end auth + billing flow with Polar webhook simulation
+- `helpers/e2e-helpers.ts` — **new** shared test helper (HTTP wrapper, DB verification toggle, webhook simulators)
 
-### Prerequisites
+## Running tests
 
-1. **Dev server must be running**: The integration tests make real HTTP requests to `http://localhost:3000`
-   ```bash
-   pnpm dev
-   ```
+Make sure your dev server is running locally:
 
-2. **Database should be set up**: Make sure your PostgreSQL database is running and migrations are applied
-   ```bash
-   docker compose up -d db
-   pnpm db:migrate
-   ```
-
-### Running the Tests
-
-Run all authentication tests:
 ```bash
-pnpm test:auth
-```
+pnpm dev
+````
 
-Run tests in watch mode (useful during development):
-```bash
-pnpm test:auth:watch
-```
+Confirm the environment variables in `.env.test` or `.env` (at minimum `DATABASE_URL` and `TEST_BASE_URL`, defaults to `http://localhost:3000`).
+
+Run the full test suite:
 
-Run all tests in the project:
 ```bash
 pnpm test
 ```
 
-## Test Coverage
-
-The authentication tests cover:
-
-- **Sign Up Flow**
-  - Successful user registration
-  - Email validation
-  - Password strength validation
-  - Duplicate email prevention
-
-- **Email Verification**
-  - Sending verification emails
-  - Verifying email with valid token
-  - Rejecting invalid tokens
-  - Auto sign-in after verification
+Run only the new E2E spec:
 
-- **Sign In Flow**
-  - Sign in with verified email
-  - Blocking unverified emails
-  - Password validation
-  - Session creation
-
-- **Session Management**
-  - Creating sessions on sign-in
-  - Getting current session
-  - Sign out functionality
-
-- **Password Reset**
-  - Sending reset emails
-  - Reset token validation
-
-- **Email Provider Testing**
-  - Testing email sending functionality
-  - Provider switching (console, mailhog, smtp, resend)
-
-## How Tests Work
-
-1. **Email Mocking**: The tests mock the `sendEmail` function to capture emails instead of actually sending them
-2. **Unique Test Users**: Each test uses a unique email address to avoid conflicts
-3. **Real API Calls**: Tests make actual HTTP requests to the auth endpoints
-4. **Session Testing**: Tests verify cookie-based session management
-
-## Debugging Tests
-
-If tests are failing:
+```bash
+pnpm run test:e2e
+```
 
-1. **Check the dev server is running** at `http://localhost:3000`
-2. **Check environment variables** - ensure `.env` is properly configured
-3. **Check the console output** - the tests log captured emails
-4. **Run individual tests** by using `.only`:
-   ```typescript
-   it.only("should verify email with valid token", async () => {
-     // test code
-   })
-   ```
+### Notes on the E2E flow
 
-## Adding New Tests
+* **Email verification**: The E2E test marks the user as verified **directly in the database** for determinism and to avoid email parsing.
+* **Polar sandbox**: The test **does not** hit Polar's network. Instead, it **simulates** Polar webhook events by invoking `polarWebhookHandlers` directly, and **mocks** `~/server/polar` to avoid SDK calls (e.g., invoice generation).
+* **Checkout URL test (optional)**: If `PLANS.pro.polarProductId` (derived from your Polar product env vars) is set, the test attempts to start checkout and asserts that a URL is returned. If not configured, it is skipped gracefully.
 
-When adding new auth features, add corresponding tests:
+If you prefer real end‑to‑end payment interactions with Polar sandbox:
 
-1. Create a new `describe` block for the feature
-2. Test both success and failure cases
-3. Mock external dependencies (like email sending)
-4. Use unique test data to avoid conflicts 
+1. Set your `POLAR_*` env vars (access token, org, product IDs).
+2. Disable the `vi.mock('~/server/polar', ...)` in the E2E test and point webhooks to your local app (e.g., via `ngrok` or the included Cloudflare tunnel profile).
+3. Ensure webhook signatures are properly configured.

tests/e2e-auth-billing.test.ts

@@ -0,0 +1,216 @@
+/**
+ * E2E: Auth + Billing flow
+ *
+ * REQUIREMENTS:
+ * - Dev server running at TEST_BASE_URL (default http://localhost:3000)
+ * - DATABASE_URL configured and reachable
+ * - These tests do NOT hit real Polar endpoints; we simulate webhooks and mock invoice generation
+ */
+
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import {
+  BASE_URL,
+  apiRequest,
+  getBillingInfo,
+  getSession,
+  saveBillingProfile,
+  setEmailVerified,
+  signInUser,
+  signUpUser,
+  simulateOrderPaidCredits,
+  simulateProSubscription,
+  startCheckout,
+  uniqueEmail,
+} from './helpers/e2e-helpers';
+import { PLANS } from '~/config/plans';
+
+// --- Mock Polar server functions BEFORE importing webhook handlers ---
+vi.mock('~/server/polar', () => {
+  return {
+    // Avoid any network to Polar during tests
+    ensureOrderInvoice: vi.fn(async (orderId: string) => ({
+      invoice_pdf: `https://example.com/invoices/${orderId}.pdf`,
+      hosted_invoice_url: `https://example.com/invoices/${orderId}`,
+    })),
+    upsertPolarCustomerByExternalId: vi.fn(async () => {
+      return { id: 'cust_mock' };
+    }),
+    // The rest of the exports aren't required by our invocation path here.
+  };
+});
+
+// Import after mock so our handlers use the mocked functions
+import { polarWebhookHandlers } from '~/server/polar-webhooks';
+
+describe('E2E • Auth + Billing', () => {
+  beforeAll(() => {
+    // Sanity notice for the developer running tests
+    // eslint-disable-next-line no-console
+    console.log(`Running E2E tests against ${BASE_URL}`);
+  });
+
+  it('1) signs up a user (free, unverified)', async () => {
+    const email = uniqueEmail('free');
+    const password = 'StrongPassw0rd!';
+    const name = 'Free User';
+
+    const { response, user } = await signUpUser({ email, password, name });
+
+    expect(response.ok).toBe(true);
+    expect(response.status).toBe(200);
+    expect(user).toBeDefined();
+    expect(user?.email).toBe(email);
+    expect(user?.name).toBe(name);
+    // In most configs, user starts unverified
+    expect(user?.emailVerified ?? false).toBe(false);
+  });
+
+  it('2) signs up a user and verifies email (free account), then can log in and fetch session', async () => {
+    const email = uniqueEmail('verified');
+    const password = 'StrongPassw0rd!';
+    const name = 'Verified User';
+
+    const { response, user } = await signUpUser({ email, password, name });
+    expect(response.ok).toBe(true);
+    expect(user?.id).toBeDefined();
+
+    // Mark verified directly in DB for E2E determinism
+    await setEmailVerified(user!.id);
+
+    const { response: signInRes, cookies } = await signInUser({ email, password });
+    expect(signInRes.ok).toBe(true);
+
+    const sessionRes = await getSession(cookies);
+    expect(sessionRes.ok).toBe(true);
+    expect(sessionRes.data?.user?.email).toBe(email);
+    expect(sessionRes.data?.user?.emailVerified).toBe(true);
+  });
+
+  it('3) logs in a user (basic sign-in flow)', async () => {
+    const email = uniqueEmail('signin');
+    const password = 'SignInPass123!';
+    const name = 'Sign In User';
+
+    const { response, user } = await signUpUser({ email, password, name });
+    expect(response.ok).toBe(true);
+
+    await setEmailVerified(user!.id);
+
+    const { response: signInRes } = await signInUser({ email, password });
+    expect(signInRes.ok).toBe(true);
+  });
+
+  it('4) signs up a user and (via Polar webhook simulation) upgrades to Pro; billing reflects Pro + monthly credits', async () => {
+    const email = uniqueEmail('pro');
+    const password = 'ProUserPass123!';
+    const name = 'Pro User';
+
+    const { response, user } = await signUpUser({ email, password, name });
+    expect(response.ok).toBe(true);
+    await setEmailVerified(user!.id);
+
+    const { response: signInRes, cookies } = await signInUser({ email, password });
+    expect(signInRes.ok).toBe(true);
+
+    // Baseline: should be free
+    const beforeBilling = await getBillingInfo(cookies);
+    expect(beforeBilling.ok).toBe(true);
+    expect(beforeBilling.data?.planId).toBe('free');
+
+    // Simulate Polar subscription active webhook => Pro
+    await simulateProSubscription(polarWebhookHandlers, { userId: user!.id, email });
+
+    const afterBilling = await getBillingInfo(cookies);
+    expect(afterBilling.ok).toBe(true);
+    expect(afterBilling.data?.planId).toBe('pro');
+    expect(afterBilling.data?.status).toBeTypeOf('string');
+    // Monthly credits should reflect Pro plan config
+    expect(afterBilling.data?.credits?.monthlyAllotment).toBe(PLANS.pro.monthlyCredits);
+
+    // Simulate an order paid that grants extra credits (e.g., 50)
+    await simulateOrderPaidCredits(polarWebhookHandlers, { userId: user!.id, email, credits: 50 });
+
+    const afterCredits = await getBillingInfo(cookies);
+    expect(afterCredits.ok).toBe(true);
+    expect(afterCredits.data?.credits?.extraCredits).toBeGreaterThanOrEqual(50);
+  });
+
+  it('5) other smoke tests: billing settings (GET, PATCH) & daily refill job', async () => {
+    const email = uniqueEmail('billing');
+    const password = 'BillingPass123!';
+    const name = 'Billing User';
+
+    const { response, user } = await signUpUser({ email, password, name });
+    expect(response.ok).toBe(true);
+    await setEmailVerified(user!.id);
+
+    const { response: signInRes, cookies } = await signInUser({ email, password });
+    expect(signInRes.ok).toBe(true);
+
+    // Load default billing profile
+    const getProfile = await apiRequest('/api/settings/billing', {
+      method: 'GET',
+      headers: cookies ? { Cookie: cookies } : {},
+    });
+    expect(getProfile.ok).toBe(true);
+    expect(getProfile.data?.profile?.billingEmail).toBe(email);
+
+    // Update billing profile
+    const patchProfile = await saveBillingProfile(cookies, {
+      billingEmail: email,
+      company: 'ACME Inc.',
+      line1: '123 Main St',
+      city: 'Metropolis',
+      state: 'CA',
+      postalCode: '94000',
+      country: 'US',
+      vat: 'US123456789',
+    });
+    expect(patchProfile.ok).toBe(true);
+
+    // Verify update succeeds on subsequent GET
+    const verifyProfile = await apiRequest('/api/settings/billing', {
+      method: 'GET',
+      headers: cookies ? { Cookie: cookies } : {},
+    });
+    expect(verifyProfile.ok).toBe(true);
+    expect(verifyProfile.data?.profile?.company).toBe('ACME Inc.');
+
+    // Daily credit refill job endpoint (noop for free users, refills for active subs)
+    const jobRes = await apiRequest('/api/jobs/daily-credit-refill', { method: 'POST' });
+    expect(jobRes.ok).toBe(true);
+    expect(jobRes.text).toContain('ok');
+  });
+
+  it('Optional) Checkout start returns a URL when Polar product IDs are configured', async () => {
+    // If product is not configured in env, skip gracefully
+    if (!PLANS.pro.polarProductId) {
+      // eslint-disable-next-line no-console
+      console.log('Skipping checkout URL test: PLANS.pro.polarProductId is not set');
+      return;
+    }
+
+    const email = uniqueEmail('checkout');
+    const password = 'CheckoutPass123!';
+    const name = 'Checkout User';
+
+    const { response, user } = await signUpUser({ email, password, name });
+    expect(response.ok).toBe(true);
+    await setEmailVerified(user!.id);
+
+    const { response: signInRes, cookies } = await signInUser({ email, password });
+    expect(signInRes.ok).toBe(true);
+
+    const checkoutRes = await startCheckout(cookies, PLANS.pro.polarProductId!);
+    expect(checkoutRes.ok).toBe(true);
+
+    // Be tolerant to response shape: { url } OR { data: { url } } OR { data: { data: { url } } }
+    const directUrl = checkoutRes.data?.url;
+    const nestedUrl = checkoutRes.data?.data?.url;
+    const deepUrl = checkoutRes.data?.data?.data?.url;
+    const anyUrl = directUrl || nestedUrl || deepUrl;
+
+    expect(typeof anyUrl).toBe('string');
+    expect(String(anyUrl)).toMatch(/^https?:\/\//);
+  });
+});