@greensecurity/javascript-sdk 0.46.0 → 0.47.0-beta.0

package/src/__tests__/apps/routes.test.ts

@@ -0,0 +1,318 @@
+/*
+ * Hand-written. Tests for app page routes (`ui_extensions.routes`): the grammar and uniqueness
+ * rules in the manifest schema, the shared matcher, the `page` surface and the `appPage`
+ * descriptor. The route sets and match cases come from `fixtures/routes.json`, which the server
+ * specs read too; see docs/third-party-apps/fullpageview-plan.md.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  APP_PAGES_SEGMENT,
+  APP_ROUTES_MAX,
+  appPagePathname,
+  effectivePostInstallAction,
+  getSurface,
+  isConcreteRoutePath,
+  isRouteDescriptor,
+  isRoutePath,
+  isSurfaceId,
+  manifestJsonSchema,
+  matchAppRoute,
+  normalizeRoutePath,
+  ROUTE_PATH_MAX_SEGMENTS,
+  ROUTE_PATH_PATTERN,
+  SURFACES,
+  surfacesForPortal,
+  validateManifest,
+  type AppManifestV2,
+  type ExtensionContext,
+  type PageRoute,
+  type ViewType,
+} from "../../apps/index.js";
+import { NON_BLANK_PATTERN } from "../../apps/manifest.js";
+
+// Resolved from the package root (vitest's cwd), as contract.test.ts does for shared/app-platform.
+const FIXTURES = resolve(process.cwd(), "src", "__tests__", "apps", "fixtures", "routes.json");
+
+interface RouteSet {
+  name: string;
+  routes: unknown[];
+}
+interface RejectedSet extends RouteSet {
+  reason: string;
+  issue: string;
+}
+interface MatchCase {
+  name: string;
+  routes: string[];
+  pathname: string;
+  expected: { index: number; path: string; params: Record<string, string> } | null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function loadFixtures(): { accepted: RouteSet[]; rejected: RejectedSet[]; matches: MatchCase[] } {
+  const parsed: unknown = JSON.parse(readFileSync(FIXTURES, "utf8"));
+  if (
+    !isRecord(parsed) ||
+    !Array.isArray(parsed["accepted"]) ||
+    !Array.isArray(parsed["rejected"]) ||
+    !Array.isArray(parsed["matches"])
+  ) {
+    throw new Error("fixtures/routes.json needs accepted, rejected and matches arrays");
+  }
+  return {
+    accepted: parsed["accepted"] as RouteSet[],
+    rejected: parsed["rejected"] as RejectedSet[],
+    matches: parsed["matches"] as MatchCase[],
+  };
+}
+
+const fixtures = loadFixtures();
+
+function manifestWithRoutes(routes: unknown, overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: 42,
+    name: "Acme Reports",
+    icon: "https://cdn.acme.com/icon.png",
+    short_description: "Reports about your vendors.",
+    version: "1.0.0",
+    configuration_instructions: "Install and sign in.",
+    support_instructions: "support@acme.com",
+    ui_extensions: {
+      bundle: {
+        url: "https://cdn.acme.com/gs-app/1.0.0/app.js",
+        integrity: "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC",
+      },
+      routes,
+    },
+    ...overrides,
+  };
+}
+
+function issuePaths(input: unknown): string[] {
+  const result = validateManifest(input);
+  return result.ok ? [] : result.issues.map((i) => i.path);
+}
+
+const page = (path: string) => ({ path, component: "Page", title: "Page" });
+
+describe("route fixtures: manifest schema", () => {
+  test("the fixture file has cases of every kind", () => {
+    expect(fixtures.accepted.length).toBeGreaterThan(0);
+    expect(fixtures.rejected.length).toBeGreaterThan(0);
+    expect(fixtures.matches.length).toBeGreaterThan(0);
+  });
+
+  test.each(fixtures.accepted.map((set) => [set.name, set] as const))("accepts %s", (_name, set) => {
+    const result = validateManifest(manifestWithRoutes(set.routes));
+    expect(result.ok ? [] : result.issues).toEqual([]);
+  });
+
+  test.each(fixtures.rejected.map((set) => [set.name, set] as const))("rejects %s", (_name, set) => {
+    expect(issuePaths(manifestWithRoutes(set.routes))).toContain(`ui_extensions.${set.issue}`);
+  });
+
+  test.each(
+    fixtures.rejected
+      .filter((set) => /^(path_format|path_too_long|too_many_segments)$/.test(set.reason))
+      .map((set) => [set.name, set] as const),
+  )("isRoutePath refuses the path of %s", (_name, set) => {
+    const route = set.routes[0];
+    expect(isRecord(route) && isRoutePath(route["path"])).toBe(false);
+  });
+
+  test("every accepted path is a route path, and every static-only one is concrete", () => {
+    for (const set of fixtures.accepted) {
+      for (const route of set.routes) {
+        const path = isRecord(route) ? route["path"] : undefined;
+        expect(isRoutePath(path), String(path)).toBe(true);
+        if (typeof path === "string") expect(isConcreteRoutePath(path)).toBe(!path.includes(":"));
+      }
+    }
+  });
+});
+
+describe("route fixtures: matchAppRoute", () => {
+  test.each(fixtures.matches.map((c) => [c.name, c] as const))("%s", (_name, c) => {
+    const routes = c.routes.map((path) => ({ path }));
+    const match = matchAppRoute(routes, c.pathname);
+    if (c.expected === null) {
+      expect(match).toBeNull();
+    } else {
+      expect(match).toEqual({ route: routes[c.expected.index], params: c.expected.params, index: c.expected.index });
+      expect(match?.route.path).toBe(c.expected.path);
+    }
+  });
+
+  test("returns the caller's own route object", () => {
+    const routes = [{ path: "/reports/:id", component: "Report", title: "Report" }];
+    expect(matchAppRoute(routes, "/reports/7")?.route).toBe(routes[0]);
+  });
+});
+
+describe("route rules", () => {
+  test("NON_BLANK_PATTERN is JavaScript's \\S on every code point, spelled out for Ruby", () => {
+    const pattern = new RegExp(NON_BLANK_PATTERN);
+    const differ: string[] = [];
+    for (let code = 0; code <= 0x10ffff; code++) {
+      if (code >= 0xd800 && code <= 0xdfff) continue;
+      const char = String.fromCodePoint(code);
+      if (pattern.test(char) !== /\S/.test(char)) differ.push(code.toString(16));
+    }
+    expect(differ).toEqual([]);
+  });
+
+  test("normalizeRoutePath renames every param to :_", () => {
+    expect(normalizeRoutePath("/")).toBe("/");
+    expect(normalizeRoutePath("/reports")).toBe("/reports");
+    expect(normalizeRoutePath("/vendors/:id/edit")).toBe("/vendors/:_/edit");
+    expect(normalizeRoutePath("/:a/:b")).toBe(normalizeRoutePath("/:x/:y"));
+  });
+
+  test("the JSON Schema carries the path grammar", () => {
+    const schema = manifestJsonSchema() as {
+      properties: {
+        ui_extensions: {
+          properties: { routes: { items: { properties: { path: { pattern: string } }; required: string[] } } };
+        };
+      };
+    };
+    const item = schema.properties.ui_extensions.properties.routes.items;
+    // zod writes `/` as `\/`; the two patterns are the same regular expression.
+    expect(item.properties.path.pattern.replace(/\\\//g, "/")).toBe(ROUTE_PATH_PATTERN);
+    expect(item.required).toEqual(["path", "component", "title"]);
+    expect(ROUTE_PATH_MAX_SEGMENTS).toBe(8);
+  });
+
+  test(`a manifest takes at most ${APP_ROUTES_MAX} routes`, () => {
+    const routes = Array.from({ length: APP_ROUTES_MAX + 1 }, (_, i) => page(`/p${i}`));
+    expect(validateManifest(manifestWithRoutes(routes.slice(0, APP_ROUTES_MAX))).ok).toBe(true);
+    expect(issuePaths(manifestWithRoutes(routes))).toContain("ui_extensions.routes");
+  });
+
+  test("routes need a bundle and a version, like views", () => {
+    const noBundle = manifestWithRoutes([page("/reports")]);
+    noBundle["ui_extensions"] = { routes: [page("/reports")] };
+    expect(issuePaths(noBundle)).toContain("ui_extensions.bundle");
+
+    const noVersion = manifestWithRoutes([page("/reports")]);
+    delete noVersion["version"];
+    noVersion["ui_extensions"] = { routes: [page("/reports")] };
+    expect(issuePaths(noVersion)).toEqual(expect.arrayContaining(["ui_extensions.bundle", "version"]));
+  });
+
+  test("a root route is a main view; any other route is not", () => {
+    const root = manifestWithRoutes([page("/")]);
+    expect(effectivePostInstallAction(root as AppManifestV2)).toEqual({ type: "app_main_view" });
+    expect(validateManifest({ ...root, post_install_action: { type: "app_main_view" } }).ok).toBe(true);
+
+    const nested = manifestWithRoutes([page("/reports")]);
+    expect(effectivePostInstallAction(nested as AppManifestV2)).toBeNull();
+    expect(issuePaths({ ...nested, post_install_action: { type: "app_main_view" } })).toContain(
+      "post_install_action.type",
+    );
+  });
+});
+
+describe("the page surface", () => {
+  test("is portal-less, wave 1, under the reserved prefix", () => {
+    expect(getSurface("page")).toEqual({
+      id: "page",
+      portal: null,
+      kind: "page",
+      objectType: null,
+      route: `/[portal]/apps/[appId]/${APP_PAGES_SEGMENT}/[...path]`,
+      idParam: "appId",
+      wave: 1,
+    });
+    expect(isSurfaceId("page")).toBe(true);
+  });
+
+  test("no other surface lives under the app pages prefix", () => {
+    // Literal portal segments too: `/company/apps/[appId]/pages` is the same place for a company user.
+    const reserved = new RegExp(`^/[^/]+/apps/\\[appId\\]/${APP_PAGES_SEGMENT}(/|$)`);
+    const offenders = SURFACES.filter((s) => s.id !== "page" && reserved.test(s.route)).map((s) => s.id);
+    expect(offenders).toEqual([]);
+  });
+
+  test("is never listed as a portal surface", () => {
+    for (const portal of ["company", "vendor", "facility", "system"] as const) {
+      expect(surfacesForPortal(portal, 2).map((s) => s.id)).not.toContain("page");
+    }
+  });
+
+  test("is not a view viewport: pages are declared as routes", () => {
+    const m = manifestWithRoutes([page("/reports")]);
+    (m["ui_extensions"] as Record<string, unknown>)["views"] = [{ viewport: "page", component: "Page" }];
+    expect(issuePaths(m)).toContain("ui_extensions.views.0.viewport");
+  });
+
+  test("appPagePathname puts the root page at the prefix itself", () => {
+    expect(appPagePathname("company", 42, "/")).toBe("/company/apps/42/pages");
+    expect(appPagePathname("vendor", 42, "/reports/7")).toBe("/vendor/apps/42/pages/reports/7");
+  });
+
+  test.each(["/../settings", "/reports/../../settings", "//evil.example", "/reports/:id", "reports", "", "/Reports"])(
+    "appPagePathname rejects %j, which is not a concrete route path",
+    (path) => {
+      expect(() => appPagePathname("company", 42, path)).toThrow(RangeError);
+    },
+  );
+
+  test.each([0, -1, 1.5, Number.NaN])("appPagePathname rejects app id %p", (appId) => {
+    expect(() => appPagePathname("company", appId, "/")).toThrow(RangeError);
+  });
+});
+
+describe("appPage route descriptors", () => {
+  test("take a concrete path in the route grammar", () => {
+    expect(isRouteDescriptor({ type: "appPage", path: "/" })).toBe(true);
+    expect(isRouteDescriptor({ type: "appPage", path: "/reports/7" })).toBe(true);
+    expect(isRouteDescriptor({ type: "appPage", path: "/pages/foo", envParams: { tab: "a" } })).toBe(true);
+    expect(isRouteDescriptor({ type: "appPage", path: "/settings" })).toBe(true);
+  });
+
+  test.each([
+    "/vendors/:id",
+    "/../settings",
+    "/reports/..",
+    "/%2e%2e/settings",
+    "/Reports",
+    "/reports/",
+    "/reports//7",
+    "reports",
+    "",
+    "/reports?x=1",
+    "https://evil.example/x",
+    `/${"a".repeat(200)}`,
+    "/a/b/c/d/e/f/g/h/i",
+  ])("refuse %j", (path) => {
+    expect(isRouteDescriptor({ type: "appPage", path })).toBe(false);
+  });
+
+  test("refuse a missing path, a non-string path and bad envParams", () => {
+    expect(isRouteDescriptor({ type: "appPage" })).toBe(false);
+    expect(isRouteDescriptor({ type: "appPage", path: 7 })).toBe(false);
+    expect(isRouteDescriptor({ type: "appPage", path: "/reports", envParams: { a: 1 } })).toBe(false);
+  });
+
+  test("the page surface is not a surface target, like settings", () => {
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "page" })).toBe(false);
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "page", objectId: 7 })).toBe(false);
+  });
+});
+
+describe("page context types", () => {
+  test("environment.route and the page view type type-check", () => {
+    const route: PageRoute = { path: "/reports/:id", pathname: "/reports/7", params: { id: "7" } };
+    const env: Pick<ExtensionContext["environment"], "surfaceId" | "route"> = { surfaceId: "page", route };
+    const viewType: ViewType = "page";
+    expect(env.route?.params["id"]).toBe("7");
+    expect(viewType).toBe("page");
+  });
+});