@owlmeans/test-integration 0.1.3

package/README.md

@@ -0,0 +1,11 @@
+# @owlmeans/test-integration
+
+Env-gated harness for integration tests of packages that talk to external services (MongoDB, Redis, S3-compatible storage, Kubernetes). Bundles helper gates and per-run namespacing — the actual driver libraries (`mongodb`, `ioredis`, `@aws-sdk/client-s3`, `@kubernetes/client-node`) stay where they already live, in the consuming integration packages.
+
+Helpers exported here:
+
+- `mongoGate()`, `redisGate()`, `s3Gate()`, `kubeGate()` — read the env keys documented in `.env.example` and return `{ skip, reason?, env }`. A `tests/context.ts` uses these to decide whether to register the corresponding service in the real test context.
+- `randomNamespace(prefix)` — short random suffix to keep DB names, key prefixes, and S3 prefixes unique per test run so suites can safely run in parallel.
+- `registerCleanup(fn)` + `runCleanups()` — opt-in `afterAll` cleanup queue.
+
+Specs do not call services through these helpers — they consume the per-package real test context built in `tests/context.ts` and only check `gates.<svc>.skip` to self-skip when the dependency is missing. See `testing-integration` skill for the full pattern.

package/build/cleanup.d.ts

@@ -0,0 +1,16 @@
+type CleanupFn = () => void | Promise<void>;
+/**
+ * Register a cleanup function that `runCleanups()` will execute (LIFO).
+ * Use from `tests/context.ts` `setup()` to schedule teardown of resources
+ * that were provisioned for the suite (DB drop, key namespace flush,
+ * uploaded objects).
+ */
+export declare const registerCleanup: (fn: CleanupFn) => void;
+/**
+ * Run all pending cleanup functions in reverse registration order.
+ * Errors are swallowed and reported to stderr so a failing cleanup
+ * cannot mask a test failure.
+ */
+export declare const runCleanups: () => Promise<void>;
+export {};
+//# sourceMappingURL=cleanup.d.ts.map

package/build/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AAAA,KAAK,SAAS,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAI3C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,SAAS,KAAG,IAE/C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAa,OAAO,CAAC,IAAI,CAUhD,CAAA"}

package/build/cleanup.js

@@ -0,0 +1,29 @@
+const queue = [];
+/**
+ * Register a cleanup function that `runCleanups()` will execute (LIFO).
+ * Use from `tests/context.ts` `setup()` to schedule teardown of resources
+ * that were provisioned for the suite (DB drop, key namespace flush,
+ * uploaded objects).
+ */
+export const registerCleanup = (fn) => {
+    queue.push(fn);
+};
+/**
+ * Run all pending cleanup functions in reverse registration order.
+ * Errors are swallowed and reported to stderr so a failing cleanup
+ * cannot mask a test failure.
+ */
+export const runCleanups = async () => {
+    while (queue.length > 0) {
+        const fn = queue.pop();
+        if (fn == null)
+            continue;
+        try {
+            await fn();
+        }
+        catch (err) {
+            console.error('@owlmeans/test-integration cleanup failed:', err);
+        }
+    }
+};
+//# sourceMappingURL=cleanup.js.map

package/build/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AAEA,MAAM,KAAK,GAAgB,EAAE,CAAA;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAa,EAAQ,EAAE;IACrD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAChB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,IAAmB,EAAE;IACnD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,EAAE,CAAA;QACtB,IAAI,EAAE,IAAI,IAAI;YAAE,SAAQ;QACxB,IAAI,CAAC;YACH,MAAM,EAAE,EAAE,CAAA;QACZ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,GAAG,CAAC,CAAA;QAClE,CAAC;IACH,CAAC;AACH,CAAC,CAAA"}

package/build/gates.d.ts

@@ -0,0 +1,29 @@
+export interface IntegrationGate<E> {
+    skip: boolean;
+    reason?: string;
+    env: Partial<E>;
+}
+export interface MongoEnv {
+    MONGO_URL: string;
+    MONGO_TEST_DB_PREFIX: string;
+}
+export declare const mongoGate: () => IntegrationGate<MongoEnv>;
+export interface RedisEnv {
+    REDIS_URL: string;
+    REDIS_TEST_KEY_PREFIX: string;
+}
+export declare const redisGate: () => IntegrationGate<RedisEnv>;
+export interface S3Env {
+    S3_ENDPOINT: string;
+    S3_KEY: string;
+    S3_SECRET: string;
+    S3_TEST_BUCKET: string;
+    S3_REGION: string;
+}
+export declare const s3Gate: () => IntegrationGate<S3Env>;
+export interface KubeEnv {
+    KUBE_CONFIG: string;
+    KUBE_TEST_OK: string;
+}
+export declare const kubeGate: () => IntegrationGate<KubeEnv>;
+//# sourceMappingURL=gates.d.ts.map

package/build/gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAChB;AAoBD,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAED,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CACiB,CAAA;AAEtE,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAED,eAAO,MAAM,SAAS,QAAO,eAAe,CAAC,QAAQ,CACkB,CAAA;AAEvE,MAAM,WAAW,KAAK;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,eAAO,MAAM,MAAM,QAAO,eAAe,CAAC,KAAK,CAI5C,CAAA;AAEH,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,QAAQ,QAAO,eAAe,CAAC,OAAO,CACU,CAAA"}

package/build/gates.js

@@ -0,0 +1,21 @@
+import { hasEnv, requireEnv } from '@owlmeans/test';
+const collect = (keys) => {
+    const env = {};
+    for (const k of keys) {
+        if (hasEnv(k))
+            env[k] = process.env[k];
+    }
+    return env;
+};
+const toIntegrationGate = (required, optional = []) => {
+    const gate = requireEnv(required);
+    const env = collect([...required, ...optional]);
+    if ('ok' in gate)
+        return { skip: false, env };
+    return { skip: true, reason: gate.reason, env };
+};
+export const mongoGate = () => toIntegrationGate(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX']);
+export const redisGate = () => toIntegrationGate(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX']);
+export const s3Gate = () => toIntegrationGate(['S3_ENDPOINT', 'S3_KEY', 'S3_SECRET', 'S3_TEST_BUCKET'], ['S3_REGION']);
+export const kubeGate = () => toIntegrationGate(['KUBE_CONFIG', 'KUBE_TEST_OK']);
+//# sourceMappingURL=gates.js.map

package/build/gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAQnD,MAAM,OAAO,GAAG,CAAI,IAA0B,EAAc,EAAE;IAC5D,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,MAAM,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAW,CAAA;IAClD,CAAC;IACD,OAAO,GAAiB,CAAA;AAC1B,CAAC,CAAA;AAED,MAAM,iBAAiB,GAAG,CACxB,QAA8B,EAC9B,WAAiC,EAAE,EACf,EAAE;IACtB,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,OAAO,CAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAA;IAClD,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;IAC7C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAA;AACjD,CAAC,CAAA;AAOD,MAAM,CAAC,MAAM,SAAS,GAAG,GAA8B,EAAE,CACvD,iBAAiB,CAAW,CAAC,WAAW,CAAC,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAOtE,MAAM,CAAC,MAAM,SAAS,GAAG,GAA8B,EAAE,CACvD,iBAAiB,CAAW,CAAC,WAAW,CAAC,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAA;AAUvE,MAAM,CAAC,MAAM,MAAM,GAAG,GAA2B,EAAE,CACjD,iBAAiB,CACf,CAAC,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,CAAC,EACxD,CAAC,WAAW,CAAC,CACd,CAAA;AAOH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAA6B,EAAE,CACrD,iBAAiB,CAAU,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export * from './gates.js';
+export * from './naming.js';
+export * from './cleanup.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}

package/build/index.js

@@ -0,0 +1,4 @@
+export * from './gates.js';
+export * from './naming.js';
+export * from './cleanup.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}

package/build/naming.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Short random suffix safe to use in DB names, Redis key prefixes, and S3
+ * object prefixes. Default 6 hex chars is enough to avoid collisions
+ * between parallel test runs while staying within MongoDB's 38-char DB
+ * name limit when combined with a sensible prefix.
+ */
+export declare const randomNamespace: (prefix: string, length?: number) => string;
+//# sourceMappingURL=naming.d.ts.map

package/build/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,EAAE,SAAQ,MAAU,KAAG,MAKpE,CAAA"}

package/build/naming.js

@@ -0,0 +1,14 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Short random suffix safe to use in DB names, Redis key prefixes, and S3
+ * object prefixes. Default 6 hex chars is enough to avoid collisions
+ * between parallel test runs while staying within MongoDB's 38-char DB
+ * name limit when combined with a sensible prefix.
+ */
+export const randomNamespace = (prefix, length = 6) => {
+    const suffix = randomBytes(Math.max(1, Math.ceil(length / 2)))
+        .toString('hex')
+        .slice(0, length);
+    return `${prefix}_${suffix}`;
+};
+//# sourceMappingURL=naming.js.map

package/build/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,SAAiB,CAAC,EAAU,EAAE;IAC5E,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;SAC3D,QAAQ,CAAC,KAAK,CAAC;SACf,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACnB,OAAO,GAAG,MAAM,IAAI,MAAM,EAAE,CAAA;AAC9B,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@owlmeans/test-integration",
+  "version": "0.1.3",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/test": "^0.1.3"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "^0.1.3",
+    "@types/bun": "^1.3.0",
+    "nodemon": "^3.1.11",
+    "typescript": "^6.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cleanup.ts

@@ -0,0 +1,30 @@
+type CleanupFn = () => void | Promise<void>
+
+const queue: CleanupFn[] = []
+
+/**
+ * Register a cleanup function that `runCleanups()` will execute (LIFO).
+ * Use from `tests/context.ts` `setup()` to schedule teardown of resources
+ * that were provisioned for the suite (DB drop, key namespace flush,
+ * uploaded objects).
+ */
+export const registerCleanup = (fn: CleanupFn): void => {
+  queue.push(fn)
+}
+
+/**
+ * Run all pending cleanup functions in reverse registration order.
+ * Errors are swallowed and reported to stderr so a failing cleanup
+ * cannot mask a test failure.
+ */
+export const runCleanups = async (): Promise<void> => {
+  while (queue.length > 0) {
+    const fn = queue.pop()
+    if (fn == null) continue
+    try {
+      await fn()
+    } catch (err) {
+      console.error('@owlmeans/test-integration cleanup failed:', err)
+    }
+  }
+}

package/src/gates.ts

@@ -0,0 +1,63 @@
+import { hasEnv, requireEnv } from '@owlmeans/test'
+
+export interface IntegrationGate<E> {
+  skip: boolean
+  reason?: string
+  env: Partial<E>
+}
+
+const collect = <E>(keys: (keyof E & string)[]): Partial<E> => {
+  const env: Record<string, string> = {}
+  for (const k of keys) {
+    if (hasEnv(k)) env[k] = process.env[k] as string
+  }
+  return env as Partial<E>
+}
+
+const toIntegrationGate = <E>(
+  required: (keyof E & string)[],
+  optional: (keyof E & string)[] = []
+): IntegrationGate<E> => {
+  const gate = requireEnv(required)
+  const env = collect<E>([...required, ...optional])
+  if ('ok' in gate) return { skip: false, env }
+  return { skip: true, reason: gate.reason, env }
+}
+
+export interface MongoEnv {
+  MONGO_URL: string
+  MONGO_TEST_DB_PREFIX: string
+}
+
+export const mongoGate = (): IntegrationGate<MongoEnv> =>
+  toIntegrationGate<MongoEnv>(['MONGO_URL'], ['MONGO_TEST_DB_PREFIX'])
+
+export interface RedisEnv {
+  REDIS_URL: string
+  REDIS_TEST_KEY_PREFIX: string
+}
+
+export const redisGate = (): IntegrationGate<RedisEnv> =>
+  toIntegrationGate<RedisEnv>(['REDIS_URL'], ['REDIS_TEST_KEY_PREFIX'])
+
+export interface S3Env {
+  S3_ENDPOINT: string
+  S3_KEY: string
+  S3_SECRET: string
+  S3_TEST_BUCKET: string
+  S3_REGION: string
+}
+
+export const s3Gate = (): IntegrationGate<S3Env> =>
+  toIntegrationGate<S3Env>(
+    ['S3_ENDPOINT', 'S3_KEY', 'S3_SECRET', 'S3_TEST_BUCKET'],
+    ['S3_REGION']
+  )
+
+export interface KubeEnv {
+  KUBE_CONFIG: string
+  KUBE_TEST_OK: string
+}
+
+export const kubeGate = (): IntegrationGate<KubeEnv> =>
+  toIntegrationGate<KubeEnv>(['KUBE_CONFIG', 'KUBE_TEST_OK'])

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './gates.js'
+export * from './naming.js'
+export * from './cleanup.js'

package/src/naming.ts

@@ -0,0 +1,14 @@
+import { randomBytes } from 'node:crypto'
+
+/**
+ * Short random suffix safe to use in DB names, Redis key prefixes, and S3
+ * object prefixes. Default 6 hex chars is enough to avoid collisions
+ * between parallel test runs while staying within MongoDB's 38-char DB
+ * name limit when combined with a sensible prefix.
+ */
+export const randomNamespace = (prefix: string, length: number = 6): string => {
+  const suffix = randomBytes(Math.max(1, Math.ceil(length / 2)))
+    .toString('hex')
+    .slice(0, length)
+  return `${prefix}_${suffix}`
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.bun.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+}