@elench/testkit 0.1.77 → 0.1.78

package/README.md

@@ -365,8 +365,31 @@ Named HTTP profiles live in `testkit.config.ts` and can be referenced by name:
 
 ```ts
 import { defineHttpSuite } from "@elench/testkit";
+import { defineConfig, profiles } from "@elench/testkit/config";
 
-const suite = defineHttpSuite({ profile: "default-auth" }, ({ req, setupData }) => {
+export default defineConfig({
+  profiles: {
+    http: {
+      defaultAuth: profiles.localJson({
+        password: "password",
+        identities: {
+          primary: {
+            email: "test@example.com",
+          },
+        },
+        session: {
+          authCookie: "session",
+        },
+        headers: {
+          contentTypeJson: true,
+          forwardedFor: "deterministic",
+        },
+      }).session(),
+    },
+  },
+});
+
+const suite = defineHttpSuite({ profile: "defaultAuth" }, ({ req, setupData }) => {
   req("GET", "/api/auth/session", setupData);
 });
 ```

package/lib/app/doctor.mjs

@@ -4,6 +4,7 @@ import ts from "typescript";
 import { discoverTests } from "../discovery/index.mjs";
 import { loadConfigContext } from "../config/index.mjs";
 import { runTestkitTypecheck } from "./typecheck.mjs";
+import { findConfigFile } from "../config/config-loader.mjs";
 
 export async function runDoctor(options = {}) {
   const checks = [];
@@ -39,6 +40,17 @@ export async function runDoctor(options = {}) {
     details: playwrightViolations,
   });
 
+  const configImportViolations = findConfigImportViolations(productDir);
+  checks.push({
+    code: "config-import-hygiene",
+    level: configImportViolations.length === 0 ? "pass" : "fail",
+    message:
+      configImportViolations.length === 0
+        ? "Repo config does not import __testkit__ helper modules"
+        : `Found ${configImportViolations.length} repo config import violation(s)`,
+    details: configImportViolations,
+  });
+
   const hasBrowserOrNextWork = discovery.files.some((entry) => entry.selectionType === "pw");
   if (hasBrowserOrNextWork) {
     const nodeCount = discovery.coverageGraph?.nodes?.length || 0;
@@ -113,6 +125,31 @@ function findPlaywrightRuntimeImportViolations(productDir) {
   return violations;
 }
 
+function findConfigImportViolations(productDir) {
+  const configFile = findConfigFile(productDir);
+  if (!configFile || !fs.existsSync(configFile)) return [];
+
+  const sourceText = fs.readFileSync(configFile, "utf8");
+  const sourceFile = ts.createSourceFile(configFile, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const violations = [];
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const specifier = statement.moduleSpecifier.text;
+    if (!isRepoLocalConfigImportViolation(specifier)) continue;
+    const position = sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile));
+    violations.push({
+      file: path.relative(productDir, configFile).split(path.sep).join("/"),
+      line: position.line + 1,
+      specifier,
+      snippet: statement.getText(sourceFile),
+    });
+  }
+
+  return violations;
+}
+
 function collectFiles(rootDir, out = []) {
   if (!fs.existsSync(rootDir)) return out;
   for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
@@ -129,6 +166,12 @@ function collectFiles(rootDir, out = []) {
   return out.sort((left, right) => left.localeCompare(right));
 }
 
+function isRepoLocalConfigImportViolation(specifier) {
+  if (typeof specifier !== "string") return false;
+  if (!specifier.startsWith(".") && !specifier.startsWith("/")) return false;
+  return specifier.includes("__testkit__");
+}
+
 function relativeViolation(productDir, absolutePath, sourceFile, statement) {
   const position = sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile));
   return {

package/lib/config-api/index.d.ts

@@ -1,4 +1,4 @@
-import type { AuthAdapter, HeaderBuilder, HttpSuiteConfig } from "../index";
+import type { HttpSuiteConfig, RuntimeEnv, RuntimeOptions } from "../index";
 
 export interface DatabaseTemplateConfig {
   inputs?: string[];
@@ -192,6 +192,187 @@ export interface TestkitFileMetadata {
   skip?: string | { reason: string };
 }
 
+export interface ProfileRequestContext {
+  actor: string;
+  actorIndex: number;
+  env: RuntimeEnv;
+  phase: string;
+}
+
+export type ProfileValueFactory<TValue> =
+  | TValue
+  | ((context: ProfileRequestContext) => TValue);
+
+export interface ProfileRequestConfig {
+  body?: ProfileValueFactory<unknown>;
+  contentTypeJson?: boolean;
+  expect?: number | number[];
+  headers?: ProfileValueFactory<Record<string, string>>;
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+}
+
+export interface SessionAuthSourceConfig {
+  key: string;
+}
+
+export interface SessionAuthHeaderConfig {
+  header?: string;
+  prefix?: string;
+  source: SessionAuthSourceConfig;
+}
+
+export interface SessionCaptureConfig {
+  auth?: SessionAuthHeaderConfig;
+  cookies?: Record<string, string>;
+  fields?: Record<string, string>;
+}
+
+export interface SessionActorConfig {
+  bootstrap?: ProfileRequestConfig | ProfileRequestConfig[];
+  login: ProfileRequestConfig;
+  session: SessionCaptureConfig;
+}
+
+export interface ProfileHeaderContext<TSession = unknown> {
+  actor: string | null;
+  env: RuntimeEnv;
+  session: TSession | null;
+}
+
+export interface ProfileSessionHeaderConfig {
+  actor?: string;
+  field: string;
+  header: string;
+}
+
+export interface DeterministicForwardedForConfig {
+  actor?: string;
+  header?: string;
+  seed?: string;
+}
+
+export interface ProfileHeaderConfig<TSession = unknown> {
+  contentTypeJson?: boolean;
+  forwardedFor?: "deterministic" | DeterministicForwardedForConfig;
+  fromSession?: ProfileSessionHeaderConfig[];
+  values?: Record<string, string> | ((context: ProfileHeaderContext<TSession>) => Record<string, string>);
+}
+
+export interface RawHttpProfileOptions {
+  env?: RuntimeEnv;
+  headers?: ProfileHeaderConfig;
+  options?: RuntimeOptions;
+}
+
+export interface SessionHttpProfileOptions {
+  actor: SessionActorConfig;
+  env?: RuntimeEnv;
+  headers?: ProfileHeaderConfig<Record<string, unknown>>;
+  options?: RuntimeOptions;
+}
+
+export interface MultiActorHttpProfileOptions {
+  actors: Record<string, SessionActorConfig>;
+  env?: RuntimeEnv;
+  headers?: ProfileHeaderConfig<Record<string, Record<string, unknown>>>;
+  options?: RuntimeOptions;
+  primaryActor?: string;
+}
+
+export interface LocalJsonIdentityContext {
+  actor: string;
+}
+
+export type LocalJsonIdentityValue = string | ((context: LocalJsonIdentityContext) => string);
+
+export interface LocalJsonActorIdentityConfig {
+  email?: LocalJsonIdentityValue;
+  loginBody?: Record<string, unknown>;
+  name?: LocalJsonIdentityValue;
+  organizationName?: LocalJsonIdentityValue;
+  password?: LocalJsonIdentityValue;
+  signupBody?: Record<string, unknown>;
+}
+
+export interface LocalJsonSessionAuthOptions {
+  header?: string;
+  prefix?: string;
+  sourceKey?: string;
+}
+
+export interface LocalJsonSessionOptions {
+  auth?: LocalJsonSessionAuthOptions;
+  authCookie?: string;
+  cookies?: Record<string, string>;
+  fields?: Record<string, string>;
+  organizationIdPath?: string;
+  refreshCookie?: string;
+}
+
+export interface LocalJsonOrganizationHeaderConfig {
+  actor?: string;
+  field?: string;
+  header?: string;
+}
+
+export interface LocalJsonHeaderOptions {
+  contentTypeJson?: boolean;
+  forwardedFor?: "deterministic" | DeterministicForwardedForConfig;
+  organization?: false | string | LocalJsonOrganizationHeaderConfig;
+  values?: Record<string, string> | ((context: ProfileHeaderContext<unknown>) => Record<string, string>);
+}
+
+export interface LocalJsonSignupOptions {
+  enabled?: boolean;
+  expect?: number | number[];
+  path?: string;
+}
+
+export interface LocalJsonLoginOptions {
+  expect?: number | number[];
+  path?: string;
+}
+
+export interface LocalJsonProfileOptions {
+  env?: RuntimeEnv;
+  headers?: LocalJsonHeaderOptions;
+  identities?: Record<string, LocalJsonActorIdentityConfig>;
+  login?: LocalJsonLoginOptions;
+  options?: RuntimeOptions;
+  password?: LocalJsonIdentityValue;
+  session?: LocalJsonSessionOptions;
+  signup?: false | LocalJsonSignupOptions;
+}
+
+export interface LocalJsonSessionProfileOptions {
+  actor?: string;
+  env?: RuntimeEnv;
+  headers?: LocalJsonHeaderOptions;
+  identity?: LocalJsonActorIdentityConfig;
+  options?: RuntimeOptions;
+}
+
+export interface LocalJsonMultiActorProfileOptions {
+  actors?: string[] | Record<string, LocalJsonActorIdentityConfig>;
+  env?: RuntimeEnv;
+  headers?: LocalJsonHeaderOptions;
+  options?: RuntimeOptions;
+  primaryActor?: string;
+}
+
+export interface LocalJsonRawProfileOptions {
+  env?: RuntimeEnv;
+  headers?: LocalJsonHeaderOptions;
+  options?: RuntimeOptions;
+}
+
+export interface LocalJsonProfileBuilder {
+  multiActor(options?: LocalJsonMultiActorProfileOptions): HttpSuiteConfig<Record<string, Record<string, unknown>>>;
+  raw(options?: LocalJsonRawProfileOptions): HttpSuiteConfig<any>;
+  session(options?: LocalJsonSessionProfileOptions): HttpSuiteConfig<Record<string, unknown>>;
+}
+
 export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime" | "env"> {
   baseUrl?: string;
   build?: BuildConfig | null;
@@ -246,7 +427,6 @@ export interface TestkitConfig {
 }
 
 export declare function defineConfig<T extends TestkitConfig>(config: T): T;
-export declare function defineHttpProfile<T extends HttpSuiteConfig>(profile: T): T;
 export declare function defineFile<T extends TestkitFileMetadata>(metadata: T): T;
 export declare const app: {
   node(options: NodeAppOptions): ServiceConfig;
@@ -269,20 +449,13 @@ export declare const database: {
 export declare const toolchain: {
   node(options?: NodeToolchainConfig): NodeToolchainConfig;
 };
-export declare function clerkSessionProfile(options?: {
-  apiBase?: string;
-  needsAuth?: boolean;
-  secretKeyEnv?: string;
-}): HttpSuiteConfig;
-export declare function jsonSessionProfile(options?: {
-  body?: (context: { env: Record<string, string> }) => unknown;
-  cookieName?: string;
-  headers?: Record<string, string>;
-  loginPath?: string;
-  passwordEnv?: string;
-  successStatus?: number;
-  usernameEnv?: string;
-}): HttpSuiteConfig;
+export declare const profiles: {
+  custom<T extends HttpSuiteConfig>(profile: T): T;
+  localJson(options?: LocalJsonProfileOptions): LocalJsonProfileBuilder;
+  multiActor(options: MultiActorHttpProfileOptions): HttpSuiteConfig<Record<string, Record<string, unknown>>>;
+  raw(options?: RawHttpProfileOptions): HttpSuiteConfig<any>;
+  session(options: SessionHttpProfileOptions): HttpSuiteConfig<Record<string, unknown>>;
+};
 
 export declare function registerRepoConfig(config: unknown): void;
 export declare function getRepoConfig(): unknown;

package/lib/config-api/index.mjs

@@ -3,21 +3,23 @@ import {
   clearRuntimeContext,
   getRepoConfig,
   getRuntimeContext,
-  getRuntimeEnv,
   registerRepoConfig,
   registerRuntimeContext,
   runtimeHttp,
   runtimeJson,
 } from "./runtime.mjs";
+import {
+  customProfile,
+  localJsonProfile,
+  multiActorProfile,
+  rawProfile,
+  sessionProfile,
+} from "./profiles.mjs";
 
 export function defineConfig(config) {
   return config || {};
 }
 
-export function defineHttpProfile(profile) {
-  return profile || {};
-}
-
 export function defineFile(metadata) {
   return metadata || {};
 }
@@ -262,73 +264,13 @@ export const toolchain = {
   node: nodeToolchain,
 };
 
-export function clerkSessionProfile(options = {}) {
-  const apiBase = options.apiBase || "https://api.clerk.com/v1";
-  const secretKeyEnv = options.secretKeyEnv || "CLERK_SECRET_KEY";
-  const needsAuth = options.needsAuth !== false;
-
-  return defineHttpProfile({
-    auth: {
-      setup() {
-        return resolveClerkSession({
-          apiBase,
-          secretKey: envValue(secretKeyEnv),
-          needsAuth,
-        });
-      },
-      headers(setupData) {
-        return getClerkAuthHeaders(setupData, { apiBase });
-      },
-    },
-  });
-}
-
-export function jsonSessionProfile(options = {}) {
-  const loginPath = options.loginPath || "/api/auth/login";
-  const cookieName = options.cookieName || "session";
-  const body =
-    typeof options.body === "function"
-      ? options.body
-      : () => ({
-          username: envValue(options.usernameEnv || "TESTKIT_USERNAME"),
-          password: envValue(options.passwordEnv || "TESTKIT_PASSWORD"),
-        });
-
-  return defineHttpProfile({
-    auth: {
-      setup({ env }) {
-        const requestBody = body({ env });
-        const res = runtimeHttp.post(`${env.BASE}${loginPath}`, JSON.stringify(requestBody), {
-          headers: {
-            "Content-Type": "application/json",
-            ...(env.routeParams || {}),
-            ...(options.headers || {}),
-          },
-        });
-
-        if (res.status !== (options.successStatus || 200)) {
-          throw new Error(`Login failed (${res.status}): ${res.body}`);
-        }
-
-        const cookie = res.cookies?.[cookieName]?.[0]?.value ?? null;
-        if (!cookie) {
-          throw new Error(`No ${cookieName} cookie returned from login`);
-        }
-
-        return {
-          cookie,
-          body: safeJson(res),
-        };
-      },
-      headers(session) {
-        if (!session?.cookie) return {};
-        return {
-          Cookie: `${cookieName}=${session.cookie}`,
-        };
-      },
-    },
-  });
-}
+export const profiles = {
+  custom: customProfile,
+  localJson: localJsonProfile,
+  multiActor: multiActorProfile,
+  raw: rawProfile,
+  session: sessionProfile,
+};
 
 export {
   clearRepoConfig,
@@ -430,101 +372,3 @@ function compiledEntryFromSource(entry, outDir) {
   const relative = compiled.startsWith("src/") ? compiled.slice(4) : compiled;
   return `${outDir}/${relative}`.replace(/\/+/g, "/");
 }
-
-function envValue(name) {
-  const env = getRuntimeEnv();
-  const value = env?.rawEnv?.[name] || env?.[name];
-  if (!value) {
-    throw new Error(`Missing required env var "${name}" for testkit config`);
-  }
-  return value;
-}
-
-function safeJson(response) {
-  try {
-    return runtimeJson(response);
-  } catch {
-    return null;
-  }
-}
-
-function resolveClerkSession({ apiBase, secretKey, needsAuth }) {
-  if (!needsAuth) {
-    return { jwt: null };
-  }
-
-  const headers = { Authorization: `Bearer ${secretKey}` };
-  const usersRes = runtimeHttp.get(`${apiBase}/users?limit=1&order_by=-created_at`, {
-    headers,
-  });
-  if (usersRes.status !== 200) {
-    throw new Error(`Clerk list users failed (${usersRes.status}): ${usersRes.body}`);
-  }
-
-  const users = runtimeJson(usersRes);
-  if (!users.length) {
-    throw new Error("No Clerk users found for testkit Clerk auth profile");
-  }
-
-  const userId = users[0].id;
-  const sessionsRes = runtimeHttp.get(
-    `${apiBase}/sessions?user_id=${userId}&status=active&limit=1`,
-    { headers }
-  );
-  if (sessionsRes.status !== 200) {
-    throw new Error(`Clerk list sessions failed (${sessionsRes.status}): ${sessionsRes.body}`);
-  }
-
-  const sessions = runtimeJson(sessionsRes);
-  if (!sessions?.length) {
-    throw new Error("No active Clerk session found for testkit Clerk auth profile");
-  }
-
-  const sessionId = sessions[0].id;
-  const tokenRes = runtimeHttp.post(`${apiBase}/sessions/${sessionId}/tokens`, null, {
-    headers: {
-      ...headers,
-      "Content-Type": "application/json",
-    },
-  });
-  if (tokenRes.status !== 200) {
-    throw new Error(`Clerk create token failed (${tokenRes.status}): ${tokenRes.body}`);
-  }
-
-  return {
-    jwt: runtimeJson(tokenRes).jwt,
-    sessionId,
-    secretKey,
-  };
-}
-
-function getClerkAuthHeaders(setupData, { apiBase }) {
-  if (!setupData?.jwt) return {};
-
-  if (!setupData.sessionId || !setupData.secretKey) {
-    return {
-      Authorization: `Bearer ${setupData.jwt}`,
-      "Content-Type": "application/json",
-    };
-  }
-
-  const tokenRes = runtimeHttp.post(`${apiBase}/sessions/${setupData.sessionId}/tokens`, null, {
-    headers: {
-      Authorization: `Bearer ${setupData.secretKey}`,
-      "Content-Type": "application/json",
-    },
-  });
-  if (tokenRes.status !== 200) {
-    return {
-      Authorization: `Bearer ${setupData.jwt}`,
-      "Content-Type": "application/json",
-    };
-  }
-
-  const nextJwt = runtimeJson(tokenRes).jwt;
-  setupData.jwt = nextJwt;
-  return {
-    Authorization: `Bearer ${nextJwt}`,
-    "Content-Type": "application/json",
-  };
-}