@testgorilla/e2e-framework

Shared Playwright e2e framework extracted from the tgo-qa-automation suite, so product repos (starting with tgo-backend) can collocate their e2e tests while reusing one battle-tested base. Design and migration plan: docs/e2e-test-collocation-plan.md.

The package lives INSIDE playwright/ (not at the repo root) because CI ships only the playwright/ directory into the tgo-playwright runtime image (WORKDIR /playwright) — the suite resolves @testgorilla/e2e-framework/* to ./packages/e2e-framework/src/* via tsconfig paths, so the source must travel with the suite.

Status — Phase 1 (dogfooded by the playwright/ suite)

Extracted so far (see the plan, §5):

| Subpath | Contents | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @testgorilla/e2e-framework/core | createBaseTest(base, expect) fixture factory (Cookiebot suppression, console/CSP + CORS monitoring, subscription stubbing, logUserEmail, credits/features mocks, e2eConfig option), applyAuthTokenToLocalStorage, timeouts, Logger/APILogger | | @testgorilla/e2e-framework/config | resolveTgEnvironment(): E2eConfig + a compatibility surface preserving every helpers/config export name (baseURL, talentApiURL(), guards, accounts, rand*Email) | | @testgorilla/e2e-framework/api | The full data-setup/API client tree: BaseAPI core + customer, admin, talent, test-taker, code-runner clients, AssessmentCreation, and the fullFlows orchestrators | | @testgorilla/e2e-framework/stubs | CurrentSubscription with the six plan payloads inlined + the stubSubscription helper | | @testgorilla/e2e-framework/enums | Product-domain enums (tests, candidates, languages, locations, …) | | @testgorilla/e2e-framework/setup | SessionArtifactStore, setup builders (bootstrapAuth, cacheAssessmentsMap, ensureSeedAssessments, writeSetupFailureFlag) and teardown builders (AssessmentArchiver, deleteTeamMembers, deleteCandidatures) | | @testgorilla/e2e-framework/email | IMAP inbox polling, email decoding, the encoded-email flags, and the slow-email-API error flag | | @testgorilla/e2e-framework/templates | Assessment test-combination templates (CandidateInviteAssessmentTests, candidateInviteTestsForEnv()) | | @testgorilla/e2e-framework/auth | Token-based login helpers (loginWithToken, loginAs*), TOTP (getOTP), and the default-password provider seam | | @testgorilla/e2e-framework/db | DbClient transaction wrapper over an injected connection + resetSsoUser (the driver, e.g. mariadb, stays consumer-side) | | @testgorilla/e2e-framework/aws | Opt-in — SSM parameter fetch; @aws-sdk/client-ssm is an optional peer dependency | | @testgorilla/e2e-framework/chargebee | Opt-in — ChargebeeAPI (plan assignment/cancellation via Chargebee + TG webhook); chargebee-typescript is an optional peer dependency |

Binary upload/camera assets live in the sibling @testgorilla/e2e-assets package (~35 MB — install only if your specs upload files or use the fake camera).

The suite consumes all of it: fixtures/baseFixture.ts layers on createBaseTest, helpers/config is a thin composition root (credential providers + suite-only values), and specs import every shared module from the package subpaths. createBaseTest takes the consumer's test/expect so the framework never loads a second @playwright/test instance.

Opt-in subpaths

/aws and /chargebee keep their SDKs out of every other consumer: the SDKs are declared as optional peer dependencies and marked external in the build, so a repo that never imports those subpaths never installs or loads them. If you do import one, add its SDK to your own devDependencies.

Deliberate changes vs the tgo-qa-automation originals

• No credential defaults. E2E_PASSWORD / E2E_CANDIDATE_PASSWORD are env-only. The structured accounts.password accessor throws with setup guidance when unset; the compatibility password const degrades to ''.
• Account index is selectable via E2E_ACCOUNT_INDEX (falls back to the CircleCI CIRCLE_NODE_INDEX behavior, so qa-automation CI is unaffected).
• Log directory is LOG_DIR (default test-results) instead of sniffing for a playwright/ cwd.

Everything else is a verbatim port — export names and const-vs-function shapes are preserved so consumers migrate with import-path rewrites only.

Usage

import { resolveTgEnvironment, baseURL, ifNotStagingRun } from '@testgorilla/e2e-framework/config';
import { DEFAULT_TIMEOUT, log } from '@testgorilla/e2e-framework/core';
import { BaseAPI } from '@testgorilla/e2e-framework/api';

@playwright/test is a peer dependency (>=1.56 <2).

Credential seams (all env-first, provider-fallback, throw-with-guidance): E2E_PASSWORD / setDefaultE2ePasswordProvider (/auth), E2E_CANDIDATE_PASSWORD / setCandidateEmailPasswordProvider (/email), RECAPTCHA_BYPASS_KEY / setRecaptchaBypassKeyProvider (/config). Chargebee is env-only: CHARGEBEE_TEST_API_KEY, CHARGEBEE_WEBHOOK_USERNAME/PASSWORD.

Develop

npm install          # from the repo root (npm workspaces)
npm run build --workspace @testgorilla/e2e-framework
npm run typecheck --workspace @testgorilla/e2e-framework