Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

47.5 KB
Raw Blame

Testing Strategy

Current State

Most testing is manual. The backend, the frontend and the public site each have unit tests for pure logic using Node's built-in test runner (no dependencies). Broader coverage is a known gap - see ROADMAP.md.

Run every test and the type check from the repository root:

npm test                            # backend, frontend, then site
npm test --workspace backend        # backend only
npm test --workspace frontend       # frontend only
npm test --workspace site           # site only
npm run typecheck                   # every TypeScript project

Each workspace's test script is node --test "tests/**/*.test.ts". The tests are TypeScript: Node strips the types and runs the files directly, which needs Node 22.18 or newer (CI uses Node 24). Node does not check types while it runs them, so a test can pass with a type error; npm run typecheck covers the tests too (backend/tests/tsconfig.json, frontend/tsconfig.node.json and site/tsconfig.node.json).

Test layout

Tests never sit next to source files. Each workspace has a tests/ folder that mirrors its source tree:

Source file Test file
backend/services/youtube/youtubeChannels.ts backend/tests/services/youtube/youtubeChannels.test.ts
backend/routes/accountRoutes.ts backend/tests/routes/accountRoutes.test.ts
backend/routes/publishingRoutes.ts backend/tests/routes/publishingRoutes.test.ts
backend/routes/settingsRoutes.ts backend/tests/routes/settingsRoutes.test.ts
backend/services/scheduledPublisher.ts backend/tests/services/scheduledPublisher.test.ts
backend/lib/scheduledPublishing.ts backend/tests/lib/scheduledPublishing.test.ts
backend/mcp/tools/analyticsTools.ts backend/tests/mcp/analyticsTools.test.ts
backend/repositories/scheduledPostRepository.ts backend/tests/repositories/scheduledPostRepository.test.ts
backend/services/tokenRefreshService.ts backend/tests/services/tokenRefreshService.test.ts
backend/repositories/accountRepository.ts backend/tests/repositories/accountRepository.test.ts
backend/middleware/errorHandler.ts backend/tests/middleware/errorHandler.test.ts
backend/middleware/clients.ts backend/tests/middleware/clients.test.ts
backend/routes/index.ts (health checks) backend/tests/routes/healthRoutes.test.ts
backend/routes/index.ts (the protected route table; the routes removed in v2.0.0 answer 404) backend/tests/routes/index.test.ts
backend/database/supabase.ts backend/tests/database/supabase.test.ts
backend/lib/redact.ts backend/tests/lib/redact.test.ts
backend/lib/circuitBreaker.ts backend/tests/lib/circuitBreaker.test.ts
backend/services/accountService.ts backend/tests/services/accountService.test.ts (and the account route tests)
backend/services/instagramConnectService.ts backend/tests/services/instagramConnectService.test.ts
backend/validators/fields.ts backend/tests/validators/fields.test.ts
supabase/migrations/*.sql and supabase/rollbacks/*.sql backend/tests/database/migrations.test.ts
frontend/src/lib/accounts.ts frontend/tests/lib/accounts.test.ts
frontend/src/lib/apiErrors.ts frontend/tests/lib/apiErrors.test.ts
backend/routes/authHookRoutes.ts backend/tests/routes/authHookRoutes.test.ts
backend/routes/instagramWebhookRoutes.ts backend/tests/routes/instagramWebhookRoutes.test.ts
backend/routes/automationRoutes.ts backend/tests/routes/automationRoutes.test.ts
backend/services/automationProcessor.ts backend/tests/services/automationProcessor.test.ts
backend/services/automationWebhookService.ts backend/tests/services/automationWebhookService.test.ts
backend/services/automationFollowupProcessor.ts backend/tests/services/automationFollowupProcessor.test.ts
backend/services/automationPublicReplyProcessor.ts backend/tests/services/automationPublicReplyProcessor.test.ts
backend/services/automationReconciler.ts backend/tests/services/automationReconciler.test.ts
backend/services/instagram/instagramMessaging.ts backend/tests/services/instagram/instagramMessaging.test.ts
backend/services/instagram/instagramComments.ts backend/tests/services/instagram/instagramComments.test.ts
backend/services/retentionService.ts backend/tests/services/retentionService.test.ts
backend/lib/automationMatching.ts, automationDelivery.ts, automationPublicReply.ts, automationRules.ts, automationReview.ts, automationHealth.ts, metaWebhookSignature.ts backend/tests/lib/ with the same names
backend/repositories/automationCommentRepository.ts backend/tests/repositories/automationCommentRepository.test.ts
backend/repositories/automationFollowupRepository.ts backend/tests/repositories/automationFollowupRepository.test.ts
backend/repositories/automationRuleRepository.ts, automationAccountRepository.ts, auditRepository.ts backend/tests/repositories/automationRuleRepository.test.ts
backend/validators/automationValidators.ts, instagramWebhookValidators.ts backend/tests/validators/ with the same names
backend/jobs/scheduled.ts backend/tests/jobs/scheduled.test.ts
frontend/src/features/automations/automationData.ts frontend/tests/features/automations/automationData.test.ts
backend/services/authEmailService.ts backend/tests/services/authEmailService.test.ts
frontend/src/lib/authErrors.ts frontend/tests/lib/authErrors.test.ts
frontend/src/lib/passwords.ts frontend/tests/lib/passwords.test.ts
frontend/src/lib/emailAddress.ts frontend/tests/lib/emailAddress.test.ts
frontend/src/lib/googleIdentity.ts frontend/tests/lib/googleIdentity.test.ts
frontend/src/lib/signInPage.ts frontend/tests/lib/signInPage.test.ts
frontend/src/lib/signedInCookie.ts frontend/tests/lib/signedInCookie.test.ts
site/index.html (the signed-in redirect script) site/tests/homeRedirect.test.ts
frontend/src/features/analytics/overview/overviewStats.ts frontend/tests/features/analytics/overview/overviewStats.test.ts
frontend/src/features/publishing/scheduleHelpers.ts frontend/tests/features/publishing/scheduleHelpers.test.ts
site/src/docs/searchShared.ts site/tests/docs/searchShared.test.ts
site/content/docs/**/*.mdx and site/src/docs/nav.ts site/tests/docs/content.test.ts
site/src/lib/chart.ts site/tests/lib/chart.test.ts
site/src/lib/format.ts site/tests/lib/format.test.ts

Backend tests are in backend/tests/database, backend/tests/jobs, backend/tests/lib, backend/tests/middleware, backend/tests/repositories, backend/tests/routes, backend/tests/services (with youtube/ and instagram/ for the platform modules) and backend/tests/validators. A route test is named after its route table (accountRoutes.test.ts) and exercises the whole stack below it: controller, service and repository. Shared test helpers (fakeSupabase.ts, fakeFetch.ts, golden.ts, routeHarness.ts, rowIds.ts, the per-platform *Fixtures.ts data) and the *.golden.json snapshots are in backend/tests/fixtures/. fakeSupabase.ts also answers rpc() for the three merge functions, running the same shallow merge on its in-memory rows (with p_only_status and the null-user cron form), and sets updated_at on every update and upsert as the database trigger does. The fake also answers in, gte, gt and limit (rows come back in stored order, so a test seeds them in the order it expects), inserts and upserts of several rows, and ignoreDuplicates upserts that return only the new rows; fakeSupabase(rows, rpcHandlers) runs any other database function the test supplies. fakeFetch.ts replies can carry headers. mockRowIds() in rowIds.ts replaces crypto.randomUUID() with numbered UUIDs, so the ids in responses and golden snapshots stay the same between runs. Wrangler only bundles files reachable from server.ts, so nothing in backend/tests/ ships in the Worker.

Frontend tests cover shared helpers in src/lib/ and src/utils/ (hold-to-confirm timing, command palette ranking, library filtering and paging, platform helpers, and a check that every Lucide icon imported in src exists) and page helpers in src/features/**, such as features/analytics/overview/overviewStats.ts. A testable helper is a plain .ts file with no JSX and no @/ or @shared/ imports, and its imports of project files (including shared/types) are relative paths that end in .ts, so Node can load it directly. It uses only erasable TypeScript (no enum, no parameter properties) and import type for types. This rule lives here, so helper files do not repeat it in a header comment.

Site tests are in site/tests/docs/ and site/tests/lib/. chart.test.ts checks the chart geometry the product previews draw with (the smooth line passes through every point and never overshoots between two), and format.test.ts the number formats they show. content.test.ts reads the MDX files in site/content/docs/ and checks that every page in site/src/docs/nav.ts has a content file and every content file is in the navigation, that the navigation slugs are unique, that every page starts with export const meta = { title, description }, that every link to another docs page points at a page that exists, and that no page uses an em or en dash. It reads nav.ts as text, because that file imports the generated JSX icons, which Node cannot load. searchShared.test.ts covers slugify(), which makes the heading anchors that search results open.

Test files import the code under test the same way, by relative path with the .ts extension (../../src/lib/accounts.ts). Type test fakes narrowly: cast a fake once to the interface it stands in for, rather than using any, which is a lint error.

The error contract has its own tests: tests/middleware/errorHandler.test.ts (the status and body for each error code, platform messages without URLs, database and unexpected errors hidden from the client, validation and malformed JSON, and unknown routes) and, on the frontend, tests/lib/apiErrors.test.ts (the message request() throws, with the request id on 5xx). Repository tests (tests/repositories/*.test.ts) check the user filter, the data merge and the DatabaseError for a failed query against the fake Supabase client, and analyticsCacheRepository.test.ts the cache keys, versions and failure cooldown. Validator tests (tests/validators/*.test.ts) check the field helpers and their messages. The failure paths around them have tests too: tests/middleware/clients.test.ts (a missing Supabase secret answers NOT_CONFIGURED naming it), tests/lib/config.test.ts (which secrets count as missing), tests/jobs/scheduled.test.ts (a cron run without them logs and stops), tests/database/supabase.test.ts (a query that never answers is cut off at the timeout, with mocked timers), tests/routes/healthRoutes.test.ts (liveness without the database, readiness, and a database failure hidden from the client) and tests/lib/redact.test.ts (URLs, Bearer tokens and token parameters removed, ordinary messages unchanged). tests/lib/circuitBreaker.test.ts covers the breaker with an injected clock: four failures still pass, the fifth pauses calls with a temporary error, the trial after 30 seconds closes or reopens it, other calls fail during the trial, client errors and cancelled calls never count, and an Instagram Graph code such as 506 is not a server error. tests/services/accountService.test.ts and instagramConnectService.test.ts cover an add or a connect that loses a race to the unique index: the add answers the usual 409, any other failed insert stays a database error, and the connect renews the stored token.

Rate limiting has its own tests: tests/lib/rateLimit/algorithms.test.ts (each algorithm's decisions, retry and reset times), tests/lib/rateLimit/limiter.test.ts (Redis path, memory fallback, circuit breaker, deny cache, eviction) and tests/middleware/rateLimit.test.ts (headers, the 429 body, route filters, IPv6 keys). The Lua scripts in lib/rateLimit/scripts.ts cannot run in Node; when you change one, change the twin function in algorithms.ts the same way and check both against each other in a Lua VM (see docs/architecture/backend/RATE_LIMITING.md).

Backend route and cron service tests (tests/routes/*Routes.test.ts, tests/services/scheduledPublisher.test.ts, tests/services/tokenRefreshService.test.ts) run the real code against tests/fixtures/fakeSupabase.ts and a scripted fetch, then compare responses, queries and outgoing requests with the tests/fixtures/*.golden.json snapshots. Route tests mount a route table with mountWithContext() from tests/fixtures/routeHarness.ts, which installs the real error handler and not-found handler and sets the request id (req-test), the signal and the context values the pipeline would set, so error responses are checked with their real { success: false, code, message, requestId } body and status. Rows tagged with tableRow(name, row) are only visible to that table, and so are rows the code inserts, which the fake tags with their table; untagged seed rows are visible to every table. A refactor must leave the snapshots unchanged. Prettier ignores the snapshots (.prettierignore), because the tests compare them byte for byte.

Scheduled publishing recovery has its own tests. tests/lib/scheduledPublishing.test.ts covers the shared rules: the 20 minute lease outlasts the 14 minute limit of both schedulers, what a run does for each container status, which Graph API codes count as temporary, when a failure retries or fails, and when the final message says publishing stopped. tests/repositories/scheduledPostRepository.test.ts runs the claim against the fake Supabase client: two schedulers claiming the same listed post (only the first gets it, and the claim counts an attempt), which claims are stale and that a takeover must match the expired claim it saw, that a post being published is not deleted, and that an edit only lands while the post is pending. The scheduled publisher recovery block in tests/services/scheduledPublisher.test.ts runs the whole publisher: a publish reply lost on the way back is checked on Instagram and marked published, an unreadable container status leaves the post claimed, an expired claim is taken over and found published or publishes its ready container, a claim inside its lease is left alone, a passing failure goes back to pending and the third fails the post, a run past its deadline claims nothing, and a post taken over after its last attempt is only checked. On the frontend, tests/features/publishing/scheduleHelpers.test.ts covers when the overdue alert counts a retried post (from its last claim) and a stuck claim (after the lease and 30 minutes).

The database migrations have their own test. tests/database/migrations.test.ts reads supabase/migrations/ and supabase/rollbacks/ and checks that every file is named <14 digit version>_<lowercase name>.sql with a unique version, that every version is a real UTC date and time as npm run db:new writes it, that every name starts with its verb (baseline, create, alter, add, index, revoke, check, replace, drop or rename), that every migration and rollback opens with one comment line holding one sentence, that the schema tree in supabase/schemas/ names the same tables, indexes, functions and triggers as the migrations (replaying every create and drop in order), that the baseline files come before every change, that every change has a rollback with the same name and every rollback has its migration, that the baselines use only if not exists for tables, indexes and columns so they can run again, that every function a migration creates revokes execute from public, anon, authenticated, that every migration from version 20261016100000 on creates at most one entity (a table, its access, a trigger, an index or a function) and has a rollback that is not empty, and that no file uses an em or en dash. It does not run the SQL; CI has no database. The migrations themselves were checked once on a local Postgres before the first push (ADR-038). The reply queue migrations (20261016120000 to 20261016122500) were checked the same way on a local Postgres with stub Supabase roles: every migration applies, 60 SQL scenario checks pass (among them eight sessions claiming at once, each job claimed by one), and the rollbacks apply in reverse with data present before the migrations apply again.

Comment automation has its own tests. tests/lib/automationMatching.test.ts covers whole-word and exact matching, case, look-alike characters, literal punctuation in keywords, and that a comment on one reel never triggers a rule for another. tests/lib/automationDelivery.test.ts covers the Graph error classes, backoff with jitter, the cooldown from Meta's usage header, and what is recorded for each answer: accepted, rate limited, blocked, temporary errors up to the fifth try, already replied, a refused token (held), not allowed, no answer (needs review), and a request the runtime refused (not sent). tests/lib/metaWebhookSignature.test.ts checks signatures with either secret, changed bodies and malformed headers. tests/fixtures/fakeAutomationQueue.ts is an in-memory twin of the claim, reserve and finish functions, following the SQL's rules, and tests/services/automationProcessor.test.ts runs the processor against it: two comments at once, three reels with their own rules, two runs competing for the same jobs (each reply sent once), a burst over the batch and per-account fairness, a timeout that is never resent, a run that stopped before and during a send, a rate limit cooling one account while another keeps sending, the hourly and per-person limits, five temporary failures, a rule turned off, a deleted reel, an expired comment, a refused token holding the account, the instance pause, a database failure on one job and on the claim, a cancelled run and one without time for a whole send handing their jobs back unstarted, and a run claiming only what its subrequests pay for. tests/services/automationWebhookService.test.ts covers intake: per-reel matching, unmatched comments kept without words, own comments, duplicates within and across notifications, accounts without rules, a failed insert, and the verify token. tests/repositories/automationCommentRepository.test.ts pages through comments stored in the same instant without skipping or repeating one, and checks the hand-back of unstarted jobs. tests/routes/instagramWebhookRoutes.test.ts runs the public route end to end (challenge, signed comment stored then answered, duplicates, either secret, bad signatures, bad bodies, the 1 MB limit, a missing secret, a database failure), and tests/routes/automationRoutes.test.ts the user routes, including every route answering 404 for another user's rule, account or item. tests/fixtures/metaWebhook.ts signs notifications the way Meta does. fakeAutomationQueue.ts also mirrors the turn-taking claim, follow-ups, expiry and review. tests/services/automationFollowupProcessor.test.ts covers followers-only replies: a follower gets the link, someone not following gets a reminder and the second ends the wait, nothing is sent when Instagram cannot say, a lost answer needs review and is never sent again, and two runs at once send each follow-up once. tests/services/automationReconciler.test.ts covers a lost reply found in the conversation (accepted, nothing sent) or not found (left for a person), and the expiry and health warning. tests/lib/automationRules.test.ts, automationReview.test.ts and automationHealth.test.ts cover the rule checks, matching a lost reply by its digest and time, and the warning line; tests/services/instagram/instagramMessaging.test.ts the send, follow check, conversation read and subscription requests; tests/repositories/automationFollowupRepository.test.ts the follow-up database calls. Public replies (ADR-044): tests/lib/automationPublicReply.test.ts covers the stable wording per comment, the text bounds, what is recorded for each answer (posted only with an id, a lost answer for review, a deleted comment skipped, a public-only cooldown and a day-long block, retries, a held account, expiry) and when a lost reply goes out again. tests/services/automationPublicReplyProcessor.test.ts runs the public processor against the fake queue: posting with the stored text while the private reply is left alone, a failed private reply never repeating the public one and a public retry never repeating the private one, a lost answer never posted again by the dispatch, two runs at once posting each reply once, a rate limit cooling public replies only, one public reply per person and post, the account's hourly limit, a public reply turned off, an interrupted run and the instance pause. tests/services/automationReconciler.test.ts also covers a lost public reply found on the second page of replies, sent again once after two full reads, never sent again with a page unread or after a second lost answer, and a read Instagram refuses. tests/services/instagram/instagramComments.test.ts covers the reply request, answers without an id, refusals and paging; tests/routes/instagramWebhookRoutes.test.ts a rule with both replies end to end, where the private reply fails, the public one is posted and a redelivery sends neither again; tests/routes/automationRoutes.test.ts the public reply retry, the refused private retry of a public-only comment, and public-only rules. The SQL functions cannot run in Node; they were checked on a local Postgres (PGlite, and Postgres 18 for the public reply functions, including eight claims at once on 10,000 waiting replies with no reply claimed twice) before the first push: deduplication, fair claims and lease recovery, each limit, pause and cooldown, a late answer for an interrupted send, stats, cascades, browser access and every rollback.

The MCP server has its own tests. tests/lib/mcp/protocol.test.ts covers parsing JSON-RPC, the two protocol eras, the header checks and the error replies; tests/lib/mcp/accessToken.test.ts and confirmation.test.ts the token format and hash, and that a confirmation fails for other arguments, another tool, another person or after five minutes. tests/services/mcpAccessService.test.ts covers creating, listing, revoking and authenticating tokens and approving clients; tests/services/mcpService.test.ts the dispatch, that read-only callers never see or run write tools, the confirmation flow, the timeout, the result size cap and the audit lines. tests/mcp/scheduledPostTools.test.ts, tests/mcp/analyticsTools.test.ts and tests/mcp/mediaTools.test.ts check each tool's input checks, paging and that another person's records are not found and tokens never appear; tests/routes/mcpRoutes.test.ts runs /mcp and /api/mcp/* in the full app (401 with the challenge, the Origin check, 405 for GET, revoked tokens). The media tools also have tests/services/mediaService.test.ts (records per person, no Cloudinary id in results, deletes with and without the API secret), tests/validators/mediaValidators.test.ts (only public https addresses) and tests/services/cloudinary/cloudinaryApi.test.ts (the request Cloudinary gets, and the signature checked against Cloudinary's documented example). On the frontend, tests/features/settings/claudeAccessData.test.ts covers the Settings section's helpers, tests/lib/oauthConsent.test.ts which return addresses the consent page accepts, and tests/lib/signInPage.test.ts that signing in returns only to a path on this site.

YouTube publishing has its own tests: tests/lib/youtubeUpload.test.ts (chunk math, the Range header, Shorts, metadata limits, backoff, failure classes, the Pacific midnight), tests/lib/tokenCrypto.test.ts (sealing, wrong key, tampering), tests/services/youtubeUploadRunner.test.ts (every runner transition, the budget and a lost lease), tests/services/youtubeConnectService.test.ts (the sign-in bound to its starter and to one of their YouTube accounts, a different channel refused and its access revoked, sealed tokens, reconnect, a refused refresh, publishing turned off with its account), tests/services/youtubeUploadService.test.ts, tests/routes/youtubeRoutes.test.ts (the callback, and a verify link only for the caller's own YouTube account) and tests/mcp/youtubeTools.test.ts; on the frontend tests/features/youtube/youtubeUploadData.test.ts and tests/features/accounts/youtubePublishingState.test.ts (each YouTube card's publishing state and the Google return errors). tests/lib/cloudinaryConfigState.test.ts covers the upload settings' loading, ready and failed states.

Comment automation for scheduled posts (#176) is covered by tests/services/postAutomationService.test.ts (one rule per published post, owned by its person, answering any comment on that post; a rule an earlier run saved is reused; lasting failures kept, passing ones retried), tests/repositories/scheduledPostRepository.test.ts (which posts wait for a rule), tests/validators/automationValidators.test.ts (the reply within 1,000 bytes) and tests/mcp/scheduledPostTools.test.ts (the confirmation shows both replies). tests/fixtures/fakeSupabase.ts reads data->field paths and not(column, 'is', null) the way PostgREST does.

The Send Email hook has its own tests: tests/lib/webhookSignature.test.ts (valid, tampered, wrong-key, multi-signature and replayed requests), tests/validators/authHookValidators.test.ts, tests/services/email/authEmails.test.ts (the email for each action, the verify links, HTML escaping and the two Secure Email Change emails), tests/repositories/emailQuotaRepository.test.ts (daily and per-address caps, hashed keys, Redis failures), tests/services/authEmailService.test.ts (Resend requests, idempotency keys, the caps and Resend's own quota errors, skipped notices) and tests/routes/authHookRoutes.test.ts (the hook error shape, and the route answering unsigned calls with 401 in the full app). tests/fixtures/authHook.ts signs requests the way Supabase Auth does. The Lua claim script cannot run in Node; the repository test runs the same rules in memory. On the frontend, tests/lib/authErrors.test.ts covers when the sign-in page shows the daily cap warning and whether it offers Google, tests/lib/emailAddress.test.ts when an address looks complete enough to enable the Continue arrow, tests/lib/googleIdentity.test.ts the label drawn on the Google button for each text option, and tests/lib/signInPage.test.ts when the sign-in page opens the dashboard for a stored session and when it leaves a sign-in on the page to finish.

The testing workflow documented here describes what should run before shipping any change.

Pre-Deployment Checklist

1. Type Check and Build Verification

# From the repository root: every TypeScript project must type-check
npm run typecheck

# The app and the public site must build without errors
npm run build

# Unit tests must pass
npm test

# Backend must bundle (Wrangler validates without deploying)
cd backend && npx wrangler deploy --dry-run

A type error or a broken build is a hard blocker. Do not deploy if either fails. Vite and Wrangler strip types without checking them, so a clean build does not mean the code type-checks. ci.yml runs these same steps (plus lint) on every pull request and branch push.

2. Lint

npm run lint

One ESLint run from the root covers the whole repository. The shared config is eslint.config.mjs at the root:

  • Every .ts and .tsx file: the ESLint recommended rules plus the typescript-eslint recommended rules (@typescript-eslint/no-explicit-any is an error)
  • frontend/**: also React hooks rules (no conditional hooks) and React Refresh rules, with browser globals; unused variables are errors unless they start with a capital letter or underscore
  • backend/**: service worker globals, because the Worker runs on the web platform, not Node; unused variables and arguments starting with _ are allowed, and unused caught errors are not reported
  • site/**: React hooks and React Refresh rules with browser globals; every unused variable is an error, capitalised names included
  • backend/tests/**, frontend/tests/**, frontend/vite.config.ts, site/vite.config.ts, site/build/**, site/tests/** and scripts/**: Node globals
  • Root *.js and *.mjs config files: the ESLint recommended rules with Node globals
  • Ignored: dist, .wrangler and node_modules anywhere, and .claude, where Claude Code keeps local worktrees (whole copies of the repository)

Lint must report 0 problems; the CI workflow fails on any error. The shadcn files that export their cva variants next to the component (badgeVariants, buttonVariants, tabsListVariants, toggleVariants, useSidebar), Intent UI's chart file with its helpers (useChart, valueToPercent, constructCategoryColors, getColorValue) and the contexts that export their hooks (useAppContext, useAuth) are listed in allowExportNames for react-refresh/only-export-components in eslint.config.mjs; editing one of those files reloads the page instead of hot-updating it. Add a name there only for the same pattern.

Formatting

Prettier and EditorConfig are configured at the root (.prettierrc.json, .prettierignore, .editorconfig): single quotes, semicolons, trailing commas, no parentheses around a single arrow function parameter, 120 columns, 2-space indentation, and 4 spaces in backend/. The existing code has not been reformatted in bulk, and no check enforces formatting. Run npm run format (Prettier --write over the whole repository) only when you intend to reformat; it skips Markdown, the shadcn files in frontend/src/components/ui, the golden snapshots and build output.

3. Manual API Verification (Backend)

For any backend change, verify the affected routes directly:

# Health check (should always work); the response carries an X-Request-Id header
curl -i https://twiligent.ujjwalkrai.workers.dev/api/health

# Readiness: 200 with { "status": "ready", "databaseMs": ..., "timestamp": ... } when the secrets are set and the database answers
curl -i https://twiligent.ujjwalkrai.workers.dev/api/health/ready

# Authenticated route (replace TOKEN with a real Supabase JWT)
curl -H "Authorization: Bearer TOKEN" https://twiligent.ujjwalkrai.workers.dev/api/accounts

# Without a token: 401 with { "success": false, "code": "UNAUTHORIZED", "message": ..., "requestId": ... }
curl -i https://twiligent.ujjwalkrai.workers.dev/api/accounts

For local testing:

npm run dev:backend   # from the repository root; wrangler dev on port 8787
# then curl http://localhost:8787/api/...

4. Manual Frontend Verification

Open the app in a browser. For each changed area, test:

Authentication (if the sign-in page, AuthContext or the Google button changed):

  • /login shows one card over a blurred dashboard picture, in light and dark mode, and the card appears before the picture
  • Code sign-in: type an address you own -> the Continue arrow enables once it looks complete -> "Check your email" -> the 6-digit code lands on Overview; an address with no account gets one the same way
  • Use password -> Email and Password with Forgot your password? -> valid credentials land on Overview; wrong ones show an error toast
  • No account yet? Create one with a password -> with Confirm email on, the code step opens and the code lands on Overview; with it off, the account opens at once
  • A password sign-in for an address that never confirmed -> a sign-in code is sent and the code view opens
  • Back returns to the first view, and from Reset your password to the password view
  • Continue with Google signs in (only on an origin listed in the OAuth client's Authorized JavaScript origins); in dark mode the button is the app's outline button with no white square behind the G, and Tab focus shows its ring
  • /login?mode=signup shows "Create your Twiligent account" and "Sign up with Google"
  • Signed in, open /login or /login?mode=signup (or the public site's Sign in) -> Overview opens without the form; signed out, the form shows
  • Signed in, open https://twiligent.ujjwal.fyi/ -> the app's Overview opens with no flash of the home page, while /docs still shows the docs; sign out, open it again -> the home page shows
  • With the daily cap reached, Continue shows the warning "Email codes are paused until tomorrow" above Google, offering Google or the password
  • Sign out -> redirects to login

Email verification codes (if the hook, its secrets or the login page changed):

  • Code sign-in with an address you own -> the code arrives from EMAIL_FROM ("Your Twiligent sign-in code" for an existing account, the verification code email for a new one), and entering it lands on Overview
  • A wrong code -> "The code is wrong or has expired"; Send a new code -> a new email, then a 60 second wait
  • Create an account with a password (Use password, Create one with a password) -> the confirmation code arrives and entering it lands on Overview
  • Sign in with a password for an unconfirmed address -> a sign-in code is sent and the code step opens
  • An unsigned call, curl -i -X POST -H "Content-Type: application/json" -d '{}' .../api/auth/email-hook -> 401 with { "error": { "http_code": 401, ... } } and no email sent
  • npx wrangler tail shows auth email sent for each code, and no code in any log line
  • To check the daily cap without spending the quota, run the Worker locally with EMAIL_DAILY_LIMIT=1 and no Redis, and send signed requests (see tests/fixtures/authHook.ts for the signing) -> the second one answers 429 with the Google message, which the sign-in page shows as the daily cap warning

Passwords (if the Password section, the reset steps or the recovery email changed):

  • Settings, Password: mismatched fields -> "The two passwords do not match"; a valid password -> saved, and signing out and in with it works
  • An account created with Google sets a password in Settings, then signs in with email and that password and sees the same accounts
  • Sign-in page, Use password, Forgot your password? -> the email step -> a recovery code arrives -> a wrong code shows "The code is wrong or has expired" -> the right code and a new password land on Overview
  • The link in the recovery email opens Settings signed in

Request pipeline (if middleware, CORS or error handling changed):

  • Every response, including errors, has an X-Request-Id header and the security headers (Content-Security-Policy, X-Frame-Options: DENY, Referrer-Policy: no-referrer, X-Content-Type-Options: nosniff)
  • curl -i -H "Origin: <FRONTEND_URL>" .../api/health returns Access-Control-Allow-Origin with that origin
  • curl -i -H "Origin: https://unlisted.example.com" .../api/health returns no Access-Control-Allow-Origin header, and the browser blocks a call from that origin
  • With the Worker on localhost, the Vite dev server on port 5173 can call it
  • A failing request returns { success: false, code, message, requestId } with the status for its code, and npx wrangler tail shows a JSON log line with the same request id
  • A 5xx error toast in the app ends with (request <id>)
  • .../api/health/ready answers 200 with databaseMs; on a local Worker with SUPABASE_SERVICE_KEY removed from .dev.vars, every route answers 503 NOT_CONFIGURED naming the secret

Rate limiting (if changed):

  • curl -i -H "CF-Connecting-IP: 203.0.113.1" http://localhost:8787/api/health shows RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset
  • More requests than the rule allows return 429 with Retry-After and { success: false, code: "RATE_LIMITED", message, requestId, retryAfter }, with a message that says when to retry
  • The Overview, bulk publishing and tracked content refresh still work without a 429

Accounts:

  • Add a YouTube channel by URL -> appears in sidebar
  • Delete an account -> removed from sidebar
  • Connect Instagram via OAuth -> OAuth popup, returns to accounts page

Analytics:

  • Overview page loads with correct totals
  • Channel analytics page loads for a YouTube account
  • Instagram analytics page loads for an Instagram account
  • Reels show as Reels (not Videos) on the Instagram analytics page and IG Content Explorer; Reels, Posts, and Videos counts add up to the items analyzed
  • Views appear per content type; items without insights show -
  • Overview Total Views includes Instagram views, and the Views tab shows the per-account content type table
  • Video explorer shows all videos, filtering works

Publishing (if changed):

  • Upload to Cloudinary works
  • Container creation succeeds
  • Status polling shows progress for video
  • Publish succeeds -> media ID shown

Database (if a migration changed):

  • npm run db:check lists only the new migrations, and npm run db:push applies them without an error
  • npm run db:status shows every migration in both the Local and Remote columns
  • npm run db:schema changes only the files of the objects the migrations touched, and they are committed
  • The anon key gets 401 permission denied on every table (including the automation tables and audit_events) and on the merge and automation functions: curl -i "<SUPABASE_URL>/rest/v1/accounts?select=id" -H "apikey: <anon key>" (repeat for settings, scheduled_posts, tracked_posts) and curl -i -X POST "<SUPABASE_URL>/rest/v1/rpc/merge_account_data" -H "apikey: <anon key>" -H "Content-Type: application/json" -d '{}'
  • The app still lists accounts, scheduled posts and tracked items, and the row counts in the Table Editor are unchanged

Comment automation (if the webhook, rules, the processor or the Instagram automation page changed):

  • curl -i "<worker>/api/webhooks/instagram?hub.mode=subscribe&hub.verify_token=<token>&hub.challenge=123" answers 123; a wrong token answers 403
  • curl -i -X POST -H "Content-Type: application/json" -d '{"object":"instagram","entry":[]}' <worker>/api/webhooks/instagram without a signature answers 401 and stores nothing
  • Create a rule on the Instagram automation page, turn it on, and the account shows Receiving comments (or Turn on comment events succeeds)
  • Test a comment on the rule editor page: a matching sample says it matches, a non-matching one says no reply, and nothing is sent
  • From another Instagram account, comment the keyword on a covered post: the private reply arrives within seconds, Activity shows Accepted by Instagram, and npx wrangler tail shows instagram webhook stored and automation reply settled with no token or comment text in any line
  • Comment the same keyword again on a post the rule does not cover: Activity shows No match without the words
  • Turn off Replies for the account, comment again: Activity shows Held; turn it back on and the reply goes out on the next run
  • Set AUTOMATION_PAUSED=true: comments are recorded and nothing is sent; remove it and they go out
  • Turn on an any-comment rule: any comment with text on a covered post gets the reply, and a keyword rule for the same posts still answers its keyword first
  • Turn on a followers-only rule (with the messages field selected in the Meta dashboard): the comment gets the follow prompt without the link; reply to it from the tester account while not following and the not-following message arrives; follow the account, reply again and the link arrives
  • Let a reply hit the account's hourly limit: it waits in place, and goes out within a minute after the limit frees
  • Turn on a rule's public reply with two wordings: a matching comment gets the private reply and one of the wordings under it, Activity shows Accepted by Instagram and Posted on separate lines, and npx wrangler tail shows automation public reply settled; the account's own reply is recorded as ignored (own_comment) and gets no answer
  • Comment twice on the same post from the tester account: the second comment gets no second public reply (Skipped)
  • Turn off the rule's private reply: the next comment gets only the public reply, its private reply shows Off and offers no retry
  • Retry a failed public reply from Activity: only the public reply goes out again, and the private reply's status does not change
  • At 375 px and 1280 px in both themes, the page, the rule editor page and the activity table fit, and the table scrolls inside its box

Forms and deletes (if a form or a delete changed):

  • Submit a form with a field missing or wrong: the message shows under the field, focus moves to it, and what was typed stays
  • Type in the rule editor or the Instagram publishing form, then click a sidebar link: a Discard changes question appears; reload the page and the draft is back
  • Delete a rule or a scheduled post: it disappears at once with an Undo toast; Undo brings it back, and without Undo it is gone after a reload 8 seconds later
  • Remove an account: the confirm works by holding the button and by pressing it twice

Scheduling (if changed):

  • Create a scheduled post -> appears in queue
  • Create a scheduled post with another user's account id (curl with your token) -> 404 Instagram account not found
  • A due post is published by the next quarter-hour cron run (npx wrangler tail shows the run)
  • Failed posts show error in UI
  • A post interrupted mid-publish (status publishing, claimed_at set more than 20 minutes ago in the SQL editor) is taken over by the next run: it ends published if its saved container already went out, without a second post on Instagram
  • A lost reply cannot leave a published post marked failed: when the run cannot confirm the outcome, the post stays publishing until a run after the lease checks the container
  • A pending post with attempts above 0 shows "Trying again on the next run" under its status
  • Deleting or editing a post while it is publishing is refused with "Cannot delete a post that is currently publishing" or "Can only edit pending posts"

Claude (MCP) (if /mcp, the tools, Settings, Claude or the consent page changed):

  • Settings, Claude shows the server address and the Claude Code command, each with a Copy button that copies it
  • Create token with no name -> "Give the token a name" under the field; with a name -> the token and the command with it appear once, focus moves to the token, and the list shows it as Read only with its last four characters
  • claude mcp add --transport http twiligent <server address> --header "Authorization: Bearer <token>", then in Claude Code ask for your accounts -> list_accounts answers with your accounts only
  • With a Read only token, Claude lists no scheduling tools; with Read and make changes, scheduling a post asks for confirmation first and only the confirmed call schedules it
  • Revoke the token -> the next tool call fails with "This access token is not valid"
  • curl -i -X POST <server address> -d '{}' -> 401 with WWW-Authenticate: Bearer realm="twiligent"; curl -i <server address> -> 405; the same POST with -H "Origin: https://evil.example" -> 403
  • With MCP_OAUTH_ENABLED=true and Supabase's OAuth server on: add a custom connector in Claude with the server address -> signed out, the consent page signs you in first and comes back -> it names the app and claude.ai, Read only is chosen -> Allow returns to Claude, and Settings, Claude lists the app under Approved apps
  • Deny on the consent page returns to Claude without access; Remove in Approved apps -> the app's next call is refused, and connecting again shows the consent page
  • /oauth/consent without authorization_id -> "Claude could not be connected" with what to do

Public site and docs (if site/ or the app's docs links changed):

Run npm run dev:site, or npm run build --workspace site and npm run preview --workspace site to check the production build.

  • The home page renders in both themes: switch with the theme toggle in the navbar, reload, and the choice is kept
  • /docs opens the docs home; the sidebar, the table of contents and the previous and next links work
  • Ctrl K (Cmd K on a Mac) focuses the docs search; searching for redis lists the Redis page and opening a result scrolls to its section
  • Code blocks are highlighted in both themes
  • After a build, site/dist/sitemap.xml and site/dist/llms.txt list every docs page
  • In the app, /docs/self-host/github (or any /docs/... path) lands on the same page of the public docs, and the Documentation item in the user menu opens the docs in a new tab
  • The app's /login?mode=signup shows "Create your Twiligent account"
  • The product previews play while on screen: the cursor in Publish clicks the upload, caption, time and Schedule post, the Analytics cursor reads the chart and opens Shorts and regular, and each bento card fills its panel down to the lower edge
  • With reduced motion on (DevTools, Rendering, prefers-reduced-motion), every preview shows its finished state and no cursor appears

5. Error State Testing

  • What happens with no accounts? (empty state)
  • What happens when the backend is unreachable? (error toast)
  • What happens when an Instagram token is expired? (descriptive error, 502)
  • What happens when YouTube API quota is exceeded? (YouTube's message propagated, 502)
  • What happens when a Worker secret is missing? (503 with a message naming what is not configured)

6. Console Error Verification

Open browser DevTools -> Console. Navigate through all changed pages.

  • No runtime errors or uncaught promise rejections
  • No failed network requests (red in Network tab)
  • No React warnings about missing keys or invalid DOM props

7. Accessibility Verification

For any new or changed UI, run the checks in docs/guidelines/UI_UX.md (Checking the work). At least:

  • Tab through all interactive elements - all must be reachable
  • Press Enter on buttons - they should activate
  • Press Space on buttons and checkboxes - they should activate
  • Check for visible focus ring on focused elements
  • Use Chrome's built-in Accessibility tab (DevTools -> Elements -> Accessibility) to verify ARIA structure
  • Run axe or Lighthouse on the changed pages in both themes
  • Confirm focus moves to the page heading after navigation and back to the opener after a dialog closes
  • Turn on reduced motion and check that nothing moves or loops

8. Responsive Layout Verification

Resize the browser to test at:

  • 320px (the WCAG reflow width, also 1280px at 400 percent zoom)
  • 375px (iPhone SE - smallest common mobile)
  • 768px (tablet)
  • 1280px (laptop)
  • 1920px (desktop)

Verify:

  • No horizontal scrolling on the page body
  • Data tables scroll within their container
  • All content is readable
  • Navigation is usable

9. Scheduled Publisher Verification

After any change to scripts/publish-scheduled.ts, backend/lib/scheduledPublishing.ts or publish-scheduled.yml:

  1. GitHub Actions -> "Instagram Scheduled Publisher" -> "Run workflow"
  2. Watch the run output
  3. Verify: "No posts due for publishing" (if no scheduled posts) or successful publish

To test the Worker's own publisher, schedule a post a few minutes ahead and watch npx wrangler tail at the next quarter-hour run.

Future Test Infrastructure

Already in place: golden tests for computeVideoAnalytics() and computeInstagramAnalytics(), route tests that run each route table, controller, service and repository against a fake Supabase client (backend/tests/fixtures/), and repository tests against the same fake. Still to add, in priority order:

  1. Tests for the repositories against a real database - using a Supabase test project
  2. End-to-end tests - Playwright for the full login -> view analytics -> publish flow