Tier C — Staging Integration

​

What Tier C is for

• scheduled side effects on a real deployment
• real argument validators, as deployed
• real Clerk JWT verification, end to end
• outbound fetch from Convex actions
• webhook round-trips and pipeline completion

​

Running it

cd apps/mobile

pnpm test:integration:smoke   # harness self-test — under 30 s, no AI spend
pnpm test:integration:fast    # everything not tagged @slow
pnpm test:integration         # full suite (30–60 min)
pnpm test:integration:orders  # one area (also: stash, collection, notebooks, gmail,
                              # achievements, dispensaries, users, subscriptions)

​

The isolated-user pattern

import { withTestUser } from '../helpers/identity';

await withTestUser(async (user) => {
  // user.client        -> ConvexHttpClient authenticated as this user
  // user.session       -> clerkUserId, email, sessionId, convexJwt, apiSessionToken
  // user.refreshAuth() -> re-mint both tokens mid-test
}, { persona: 'orders-projection' });

​

The production guard

​

Required environment (names only)

​

The admin runner

​

Tags

​

Cost and blast radius

• Trigger.dev runs land in the prod environment, sharing queues, concurrency, and cost with real user work. An abandoned run keeps executing and keeps billing after Vitest has moved on — which is why the harness cancels a run it abandons on timeout, and why the CI concurrency group never cancels a run in flight.
• The notebook pipeline is a deterministic builder with no model call in its path, so that suite’s AI spend is effectively nil (compute is a fraction of a cent per full run). A case that forces genuine strain research is the expensive exception.
• Gmail classification calls a real model for candidates that miss the fast path. Cost scales with the scan window, so the window stays pinned narrow (~30 days). If a Gmail case fails on volume, do not widen the window to “get more signal”.
• Dispensary menu scans are paid per cold scan (5–6 minutes each) and run only under the paid opt-in.
• The Hono API leg hits the deployment real users hit, at production rate limits. Keep API assertions read-only and user-scoped.
• retry: 0 is deliberate. Never raise it to paper over flakiness — that pays twice for the same signal. Fix the flake or quarantine it with a tracked reason.
• Staging is shared by every non-production build plus a daily cron. Never assert on a global count, a “latest N” listing, or a cross-user aggregate.

​

Gmail: the one shared-account exception

• runs against the identity named by GMAIL_DIAGNOSTIC_EMAIL, not an isolated user;
• is tagged @shared-account and must be serialized — one Gmail Tier C case at a time, and never while the Revyl order-import workflow is running, since both drive the same mailbox and the same per-user queue;
• must clean up after itself explicitly, because the isolated-user teardown does not apply;
• must pin a narrow scan window and assert on candidate shape, not exhaustiveness.

​

Writing a new suite

/**
 * @<area> — staging integration.
 *
 * Limitation: ConvexHttpClient has no subscriptions; convergence is polled.
 */
import { describe, expect, it } from 'vitest';

import { missingEnv, tierCConfigured } from '../env';
import { seedLaunchSmokeOrder } from '../helpers/fixtures';
import { withTestUser } from '../helpers/identity';
import { waitFor } from '../helpers/wait';

if (!tierCConfigured) {
  console.info(`[tier-c] <area> skipped — missing env: ${missingEnv.join(', ')}`);
}

describe.skipIf(!tierCConfigured)('@<area> <Area> — staging integration', () => {
  it('@P0 projects an order into the stash', async () => {
    await withTestUser(async (user) => {
      await seedLaunchSmokeOrder(user);

      const stash = await waitFor(
        () => user.client.query(api.stash.getStash, {}),
        rows => rows.length > 0,
        { label: 'order to project into stash', timeoutMs: 60_000 },
      );
      expect(stash.length).toBeGreaterThan(0);
    }, { persona: '<area>-happy-path' });
  });
});

• Prefer the public fixtures — they run the real validators, the real identity guard, and the real scheduled side effects, which is the whole point. Reach for admin fixtures only when a case needs data no public mutation can create.
• Scope every assertion to the test user’s own Clerk user id.
• Never string-compare a Trigger.dev run status; use the classifier helper, which fails closed.
• No any — parse boundaries as unknown and narrow.
• Log anything derived from real receipts or orders through the privacy-safe diagnostics helper. Tier C output lands in CI logs.

​

Troubleshooting

​

Related