@igstack/app-catalog-test-kit 0.18.6

package/src/mock-backend/MockBackendConfigurer.ts

@@ -0,0 +1,97 @@
+import type {
+  AppApprovalMethod,
+  GroupingTagDefinition,
+  Resource,
+} from '@igstack/app-catalog-backend-core'
+import type { MockDb } from './MockDb'
+import type { MockUserContext, UserConfig } from './MockUserContext'
+
+let counter = 0
+
+function nextId(): string {
+  counter++
+  return `test-id-${counter}`
+}
+
+function nextSlug(): string {
+  return `app-${counter}`
+}
+
+export class MockBackendConfigurer {
+  constructor(
+    readonly db: MockDb,
+    readonly userContext: MockUserContext,
+  ) {}
+
+  withApp(overrides?: Partial<Resource>): Resource {
+    const id = overrides?.id ?? nextId()
+    const app: Resource = {
+      id,
+      slug: overrides?.slug ?? nextSlug(),
+      displayName: overrides?.displayName ?? `App ${counter}`,
+      description: overrides?.description,
+      tags: overrides?.tags ?? [],
+      screenshotIds: overrides?.screenshotIds ?? [],
+      ...overrides,
+    }
+    this.db.upsertResource(app)
+    return app
+  }
+
+  withTag(overrides?: Partial<GroupingTagDefinition>): GroupingTagDefinition {
+    const def: GroupingTagDefinition = {
+      prefix: overrides?.prefix ?? `tag-${nextId()}`,
+      displayName: overrides?.displayName ?? 'Tag',
+      description: overrides?.description ?? '',
+      values: overrides?.values ?? [],
+      ...overrides,
+    }
+    this.db.setTagDefinitions([...this.db.tagsDefinitions, def])
+    return def
+  }
+
+  withApprovalMethod(
+    overrides?: Partial<AppApprovalMethod>,
+  ): AppApprovalMethod {
+    const slug = overrides?.slug ?? `method-${nextId()}`
+    const method = {
+      slug,
+      type: 'service' as const,
+      displayName: overrides?.displayName ?? 'Approval Method',
+      config: {},
+      ...overrides,
+    } as AppApprovalMethod
+    this.db.setApprovalMethods([...this.db.approvalMethods, method])
+    return method
+  }
+
+  withSubResource(
+    overrides: Partial<Resource> & { appSlug: string },
+  ): Resource {
+    const appSlug = overrides.appSlug
+    const id = overrides.id ?? nextId()
+    const resource: Resource = {
+      id,
+      slug: overrides.slug ?? `sr-${id}`,
+      displayName: overrides.displayName ?? `Sub Resource ${counter}`,
+      aliases: overrides.aliases ?? [],
+      approverSlugs: overrides.approverSlugs ?? [],
+      parentSlug: appSlug,
+      tier: overrides.tier,
+      ownerPersonSlug: overrides.ownerPersonSlug,
+      accessRequest: overrides.accessRequest,
+      description: overrides.description,
+    }
+    this.db.upsertResource(resource)
+    return resource
+  }
+
+  withUser(overrides: Partial<UserConfig>): void {
+    this.userContext.setUser(overrides)
+  }
+}
+
+/** Reset the counter between tests */
+export function resetConfigurerCounter(): void {
+  counter = 0
+}

package/src/mock-backend/MockDb.ts

@@ -0,0 +1,66 @@
+import type {
+  AppApprovalMethod,
+  AppCatalogData,
+  GroupingTagDefinition,
+  Resource,
+} from '@igstack/app-catalog-backend-core'
+
+export class MockDb {
+  resources: Resource[] = []
+  tagsDefinitions: GroupingTagDefinition[] = []
+  approvalMethods: AppApprovalMethod[] = []
+
+  upsertResource(resource: Resource): void {
+    this.resources = [
+      ...this.resources.filter((r) => r.id !== resource.id),
+      resource,
+    ]
+  }
+
+  /** @deprecated Use upsertResource */
+  upsertApp(app: Resource): void {
+    this.upsertResource(app)
+  }
+
+  getResources(): Resource[] {
+    return this.resources
+  }
+
+  /** @deprecated Use getResources */
+  getApps(): Resource[] {
+    return this.getResources()
+  }
+
+  getResource(slug: string): Resource {
+    const resource = this.resources.find((r) => r.slug === slug)
+    if (!resource) {
+      throw new Error(
+        `MockDb: resource with slug "${slug}" not found. Available: ${this.resources.map((r) => r.slug).join(', ')}`,
+      )
+    }
+    return resource
+  }
+
+  /** @deprecated Use getResource */
+  getApp(slug: string): Resource {
+    return this.getResource(slug)
+  }
+
+  setTagDefinitions(defs: GroupingTagDefinition[]): void {
+    this.tagsDefinitions = defs
+  }
+
+  setApprovalMethods(methods: AppApprovalMethod[]): void {
+    this.approvalMethods = methods
+  }
+
+  getAppCatalogData(): AppCatalogData {
+    return {
+      resources: this.resources,
+      tagsDefinitions: this.tagsDefinitions,
+      approvalMethods: this.approvalMethods,
+      persons: [],
+      groups: [],
+    }
+  }
+}

package/src/mock-backend/MockService.ts

@@ -0,0 +1,18 @@
+import type { AppCatalogData } from '@igstack/app-catalog-backend-core'
+import type { MockDb } from './MockDb'
+import type { MockUserContext } from './MockUserContext'
+
+export class MockService {
+  constructor(
+    readonly db: MockDb,
+    readonly userContext: MockUserContext,
+  ) {}
+
+  getAppCatalogData(): AppCatalogData {
+    return this.db.getAppCatalogData()
+  }
+
+  getSessionResponse(): object | null {
+    return this.userContext.getSessionResponse()
+  }
+}

package/src/mock-backend/MockUserContext.ts

@@ -0,0 +1,42 @@
+export interface UserConfig {
+  name: string
+  isAdmin: boolean
+  isAuthenticated: boolean
+}
+
+const defaultUser: UserConfig = {
+  name: 'Test User',
+  isAdmin: false,
+  isAuthenticated: true,
+}
+
+export class MockUserContext {
+  private user: UserConfig = { ...defaultUser }
+
+  setUser(overrides: Partial<UserConfig>): void {
+    this.user = { ...this.user, ...overrides }
+  }
+
+  getUser(): UserConfig {
+    return this.user
+  }
+
+  getSessionResponse(): object | null {
+    if (!this.user.isAuthenticated) {
+      return null
+    }
+    return {
+      user: {
+        id: 'test-user-id',
+        email: `${this.user.name.toLowerCase().replace(/\s/g, '.')}@test.com`,
+        name: this.user.name,
+        isAdmin: this.user.isAdmin,
+      },
+      session: {
+        id: 'test-session-id',
+        userId: 'test-user-id',
+        expiresAt: new Date(Date.now() + 86400000).toISOString(),
+      },
+    }
+  }
+}

package/src/mock-backend/magazines.ts

@@ -0,0 +1,245 @@
+import type { MockBackendConfigurer } from './MockBackendConfigurer'
+import type { BrowserStateCfg } from './BrowserStateCfg'
+import type { NetworkConfigurerCfg } from '../mock-network/NetworkConfigurerCfg'
+
+// ---------------------------------------------------------------------------
+// Core types
+// ---------------------------------------------------------------------------
+
+export interface ConfigurerContext {
+  backendCfg: MockBackendConfigurer
+  browserStateCfg: BrowserStateCfg
+  networkCfg: NetworkConfigurerCfg
+}
+
+/** A magazine is a function that configures the context */
+export type Magazine = (ctx: ConfigurerContext) => void
+
+// ---------------------------------------------------------------------------
+// Full magazine features
+// ---------------------------------------------------------------------------
+
+interface FullFeatures {
+  prepopulateCache?: boolean
+  dismissOnboarding?: boolean
+}
+
+function fullMagazine(
+  features: FullFeatures,
+  postConfigure?: Magazine,
+): Magazine {
+  return (ctx) => {
+    const { backendCfg, browserStateCfg } = ctx
+
+    // Approval methods — all 3 types
+    const supportPortal = backendCfg.withApprovalMethod({
+      slug: 'it-support',
+      type: 'service',
+      displayName: 'Support Portal',
+      config: {
+        url: 'https://support.example.com',
+        description: 'General IT support desk',
+      },
+    })
+    backendCfg.withApprovalMethod({
+      slug: 'ops-support',
+      type: 'service',
+      displayName: 'Ops Portal',
+      config: { url: 'https://opsdesk.example.com' },
+    })
+    const managerApproval = backendCfg.withApprovalMethod({
+      slug: 'manager-approval',
+      type: 'custom',
+      displayName: 'Manager Approval',
+      config: {},
+    })
+    backendCfg.withApprovalMethod({
+      slug: 'self-service',
+      type: 'custom',
+      displayName: 'Self-Service',
+      config: {},
+    })
+
+    // Tag definitions
+    backendCfg.withTag({
+      prefix: 'category',
+      displayName: 'Category',
+      description: 'Application category',
+      values: [
+        {
+          value: 'project-management',
+          displayName: 'Project Management',
+          description: '',
+        },
+        {
+          value: 'communication',
+          displayName: 'Communication',
+          description: '',
+        },
+        { value: 'internal', displayName: 'Internal Tools', description: '' },
+      ],
+    })
+    backendCfg.withTag({
+      prefix: 'team',
+      displayName: 'Team',
+      description: 'Owning team',
+      values: [
+        { value: 'engineering', displayName: 'Engineering', description: '' },
+        { value: 'platform', displayName: 'Platform', description: '' },
+      ],
+    })
+
+    // Apps
+    backendCfg.withApp({
+      slug: 'taskflow',
+      displayName: 'TaskFlow',
+      description: 'Project tracking and issue management',
+      tags: ['category:project-management', 'team:engineering'],
+      screenshotIds: ['ss-taskflow-1', 'ss-taskflow-2', 'ss-taskflow-3'],
+      appUrl: 'https://taskflow.example.com',
+      accessRequest: {
+        approvalMethodSlug: supportPortal.slug,
+        comments: 'Submit a ticket',
+      },
+    })
+
+    backendCfg.withApp({
+      slug: 'teamchat',
+      displayName: 'TeamChat',
+      description: 'Team messaging and collaboration',
+      tags: ['category:communication', 'team:platform'],
+      screenshotIds: ['ss-teamchat-1'],
+      appUrl: 'https://teamchat.example.com',
+    })
+
+    const newTool = backendCfg.withApp({
+      slug: 'new-tool',
+      displayName: 'New Tool',
+      description: 'The modern replacement',
+      tags: ['category:internal'],
+    })
+
+    backendCfg.withApp({
+      slug: 'old-tool',
+      displayName: 'Old Tool',
+      description: 'Legacy project tracker',
+      tags: ['category:project-management'],
+      deprecated: {
+        type: 'deprecated',
+        comment: 'Replaced by New Tool',
+        replacementSlug: newTool.slug,
+      },
+    })
+
+    backendCfg.withApp({
+      slug: 'legacy-app',
+      displayName: 'Legacy App',
+      description: 'Still works but discouraged',
+      tags: ['category:internal'],
+      deprecated: {
+        type: 'discouraged',
+        comment: 'Consider using alternatives',
+      },
+    })
+
+    backendCfg.withApp({
+      slug: 'internal-portal',
+      displayName: 'Internal Portal',
+      description: 'Company intranet portal',
+      tags: ['category:internal', 'team:platform'],
+      screenshotIds: ['ss-portal-1'],
+      accessRequest: {
+        approvalMethodSlug: managerApproval.slug,
+        comments: 'Requires manager approval',
+      },
+    })
+
+    backendCfg.withApp({
+      slug: 'admin-console',
+      displayName: 'Admin Console',
+      description: 'System administration dashboard',
+      tags: ['category:internal', 'team:engineering'],
+    })
+
+    // Apply features
+    if (features.dismissOnboarding) {
+      browserStateCfg.dismissOnboarding()
+    }
+    if (features.prepopulateCache) {
+      browserStateCfg.withOfflineData()
+    }
+
+    // Apply post-configurer (for test-specific overrides)
+    postConfigure?.(ctx)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Single magazine
+// ---------------------------------------------------------------------------
+
+function singleMagazine(postConfigure?: Magazine): Magazine {
+  return (ctx) => {
+    const { backendCfg } = ctx
+
+    const method = backendCfg.withApprovalMethod({
+      slug: 'it-support',
+      type: 'service',
+      displayName: 'Support Portal',
+      config: { url: 'https://support.example.com' },
+    })
+
+    backendCfg.withTag({
+      prefix: 'category',
+      displayName: 'Category',
+      description: 'Application category',
+      values: [
+        {
+          value: 'project-management',
+          displayName: 'Project Management',
+          description: '',
+        },
+      ],
+    })
+
+    backendCfg.withApp({
+      slug: 'taskflow',
+      displayName: 'TaskFlow',
+      description: 'Project tracking and issue management',
+      tags: ['category:project-management'],
+      screenshotIds: ['screenshot-taskflow-1', 'screenshot-taskflow-2'],
+      appUrl: 'https://taskflow.example.com',
+      accessRequest: {
+        approvalMethodSlug: method.slug,
+        comments: 'Submit a ticket to IT',
+      },
+    })
+
+    postConfigure?.(ctx)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Magazine entries
+// ---------------------------------------------------------------------------
+
+export const magazine = {
+  /** No apps, no tags, no approval methods */
+  empty: (() => {}) satisfies Magazine,
+
+  /** 1 app (TaskFlow), 1 tag, 1 approval method — accepts optional post-configurer */
+  single: (postConfigure?: Magazine) => singleMagazine(postConfigure),
+
+  /** Full catalog, first-time user — accepts optional post-configurer */
+  full: (postConfigure?: Magazine) => fullMagazine({}, postConfigure),
+
+  /** Full catalog, returning user (cache + onboarding dismissed) — accepts optional post-configurer */
+  fullReturningUser: (postConfigure?: Magazine) =>
+    fullMagazine(
+      { prepopulateCache: true, dismissOnboarding: true },
+      postConfigure,
+    ),
+
+  /** Inline custom configurer — pass-through for ad-hoc tests */
+  custom: (fn: Magazine): Magazine => fn,
+}

package/src/mock-network/NetworkCatalog.ts

@@ -0,0 +1,30 @@
+import type { RequestHandler } from 'msw'
+
+export interface NetworkInterceptor {
+  scopeKey: string[]
+  handler: RequestHandler
+}
+
+export class NetworkCatalog {
+  private interceptors: NetworkInterceptor[] = []
+
+  add(interceptor: NetworkInterceptor): void {
+    this.interceptors.push(interceptor)
+  }
+
+  replace(scopeKey: string[], handler: RequestHandler): void {
+    // Remove existing interceptor with matching key, add new one
+    this.interceptors = this.interceptors.filter(
+      (i) => !this.keysMatch(i.scopeKey, scopeKey),
+    )
+    this.interceptors.push({ scopeKey, handler })
+  }
+
+  getHandlers(): RequestHandler[] {
+    return this.interceptors.map((i) => i.handler)
+  }
+
+  private keysMatch(existing: string[], search: string[]): boolean {
+    return search.every((k) => existing.includes(k))
+  }
+}

package/src/mock-network/NetworkConfigurerCfg.ts

@@ -0,0 +1,24 @@
+import type { NetworkCatalog } from './NetworkCatalog'
+import type { MockService } from '../mock-backend/MockService'
+
+export type NetworkOverrideFn = (
+  catalog: NetworkCatalog,
+  service: MockService,
+) => void
+
+/**
+ * Data-carrier that collects network override callbacks.
+ * Does not execute anything — `given()` applies overrides after building the default catalog.
+ */
+export class NetworkConfigurerCfg {
+  private _overrides: NetworkOverrideFn[] = []
+
+  /** Register a callback to modify the network catalog after default handlers are set up */
+  overrideConfig(fn: NetworkOverrideFn): void {
+    this._overrides.push(fn)
+  }
+
+  get overrides(): NetworkOverrideFn[] {
+    return this._overrides
+  }
+}

package/src/mock-network/SharedNetwork.ts

@@ -0,0 +1,100 @@
+import { HttpResponse, http } from 'msw'
+import { createTRPCMsw, httpLink } from 'msw-trpc'
+import type { TRPCRouter } from '@igstack/app-catalog-backend-core'
+import type { MockService } from '../mock-backend/MockService'
+import type { NetworkInterceptor } from './NetworkCatalog'
+
+const trpcMsw = createTRPCMsw<TRPCRouter>({
+  links: [httpLink({ url: '/api/trpc' })],
+})
+
+// 1x1 transparent PNG placeholder
+const PLACEHOLDER_PNG = new Uint8Array([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49,
+  0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06,
+  0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4, 0x89, 0x00, 0x00, 0x00, 0x0a, 0x49, 0x44,
+  0x41, 0x54, 0x78, 0x9c, 0x62, 0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0xe5, 0x27,
+  0xde, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60,
+  0x82,
+])
+
+export const SharedNetwork = {
+  appCatalogQuery(service: MockService): NetworkInterceptor {
+    return {
+      scopeKey: ['appCatalog-query'],
+      handler: trpcMsw.appCatalog.getData.query(() => {
+        return service.getAppCatalogData()
+      }),
+    }
+  },
+
+  authGetSession(service: MockService): NetworkInterceptor {
+    return {
+      scopeKey: ['auth-session'],
+      handler: http.get(/\/api\/auth\/session/, () => {
+        const session = service.getSessionResponse()
+        if (!session) {
+          return HttpResponse.json(
+            { error: 'Not authenticated' },
+            { status: 401 },
+          )
+        }
+        return HttpResponse.json(session)
+      }),
+    }
+  },
+
+  authGetProviders(overrides?: {
+    devLoginEnabled?: boolean
+  }): NetworkInterceptor {
+    return {
+      scopeKey: ['auth-providers'],
+      handler: trpcMsw.auth.getProviders.query(() => {
+        return {
+          providers: [] as string[],
+          devLoginEnabled: overrides?.devLoginEnabled ?? false,
+        }
+      }),
+    }
+  },
+
+  authSignOut(): NetworkInterceptor {
+    return {
+      scopeKey: ['auth-sign-out'],
+      handler: http.post(/\/api\/auth\/sign-out/, () => {
+        return HttpResponse.json({ ok: true })
+      }),
+    }
+  },
+
+  authDevLogout(): NetworkInterceptor {
+    return {
+      scopeKey: ['auth-dev-logout'],
+      handler: http.post(/\/api\/auth\/dev-logout/, () => {
+        return HttpResponse.json({ ok: true })
+      }),
+    }
+  },
+
+  screenshotBinary(): NetworkInterceptor {
+    return {
+      scopeKey: ['screenshot'],
+      handler: http.get(/\/api\/screenshots\/.*/, () => {
+        return new HttpResponse(PLACEHOLDER_PNG, {
+          headers: { 'Content-Type': 'image/png' },
+        })
+      }),
+    }
+  },
+
+  iconBinary(): NetworkInterceptor {
+    return {
+      scopeKey: ['icon'],
+      handler: http.get(/\/api\/icons\/.*/, () => {
+        return new HttpResponse(PLACEHOLDER_PNG, {
+          headers: { 'Content-Type': 'image/png' },
+        })
+      }),
+    }
+  },
+}

package/src/mock-network/errorFactories.ts

@@ -0,0 +1,28 @@
+import { HttpResponse, http } from 'msw'
+import type { RequestHandler } from 'msw'
+
+/**
+ * Simulates a network-level connection reset error.
+ * This is what happens when the backend is completely unreachable.
+ */
+export function makeConnectionResetError(): RequestHandler {
+  return http.get(/\/api\/trpc\/appCatalog\.getData/, () => {
+    return HttpResponse.error()
+  })
+}
+
+/**
+ * Simulates a reverse proxy returning HTML instead of JSON
+ * (e.g., nginx 502 Bad Gateway page).
+ */
+export function makeHtmlResponseError(): RequestHandler {
+  return http.get(/\/api\/trpc\/appCatalog\.getData/, () => {
+    return new HttpResponse(
+      '<html><head><title>502 Bad Gateway</title></head><body><h1>502 Bad Gateway</h1><p>The server is temporarily unable to service your request.</p></body></html>',
+      {
+        status: 502,
+        headers: { 'Content-Type': 'text/html' },
+      },
+    )
+  })
+}

package/src/mock-network/makeNetworkReplyWithCatalog.ts

@@ -0,0 +1,19 @@
+import type { MockService } from '../mock-backend/MockService'
+import { NetworkCatalog } from './NetworkCatalog'
+import { SharedNetwork } from './SharedNetwork'
+
+export function makeNetworkReplyWithCatalog(
+  service: MockService,
+): NetworkCatalog {
+  const catalog = new NetworkCatalog()
+
+  catalog.add(SharedNetwork.appCatalogQuery(service))
+  catalog.add(SharedNetwork.authGetSession(service))
+  catalog.add(SharedNetwork.authGetProviders())
+  catalog.add(SharedNetwork.authSignOut())
+  catalog.add(SharedNetwork.authDevLogout())
+  catalog.add(SharedNetwork.screenshotBinary())
+  catalog.add(SharedNetwork.iconBinary())
+
+  return catalog
+}