Structure e2e API helpers (#46041)

* Refactor dashboard helpers to TypeScript

* Reuse existing helper

* Refactor cy.createQuestionAndDashboard to a function helper
- there was no good place to put it, so I also created new helpers/api directory
- and I moved all helpers using cy.request (with 1 exception, where a CSV download helper also does a bunch of assertions) in there

* Merge TS command definitions into a single file

* Export types

* Make dashboardDetails optional

* Export StructuredQuestionDetails

* Remove duplicated function

* Extract createNativeQuestion to separate file
- 1 exported helper per file, no exceptions!

* Reuse const

* Remove old definitions

* Add missing export

e2e/support/commands.js

 import "./commands/ui/button";
 import "./commands/ui/icon";
 
+import "./commands/api/index";
 import "./commands/api/alert";
-import "./commands/api/question";
-import "./commands/api/dashboard";
 import "./commands/api/dashboardCard";
-import "./commands/api/collection";
 import "./commands/api/moderation";
 import "./commands/api/pulse";
 import "./commands/api/user";
 import "./commands/api/timeline";
 
-import "./commands/api/composite/createQuestionAndDashboard";
 import "./commands/api/composite/createNativeQuestionAndDashboard";
 import "./commands/api/composite/createQuestionAndAddToDashboard";
 import "./commands/api/composite/createDashboardWithQuestions";

e2e/support/commands/api/collection.ts

-import { archiveCollection, createCollection } from "e2e/support/helpers";
-
-declare global {
-  namespace Cypress {
-    interface Chainable {
-      /**
-       * @deprecated Use function helper instead, i.e.
-       * ```
-       * import { archiveCollection } from "e2e/support/helpers"
-       * ```
-       */
-      archiveCollection: typeof archiveCollection;
-
-      /**
-       * @deprecated Use function helper instead, i.e.
-       * ```
-       * import { createCollection } from "e2e/support/helpers"
-       * ```
-       */
-      createCollection: typeof createCollection;
-    }
-  }
-}
-
-Cypress.Commands.add("archiveCollection", archiveCollection);
-Cypress.Commands.add("createCollection", createCollection);

e2e/support/commands/api/composite/createQuestionAndDashboard.js

-Cypress.Commands.add(
-  "createQuestionAndDashboard",
-  ({ questionDetails, dashboardDetails, cardDetails } = {}) => {
-    cy.createQuestion(questionDetails).then(({ body: { id: questionId } }) => {
-      cy.createDashboard(dashboardDetails).then(
-        ({ body: { id: dashboardId } }) => {
-          cy.request("PUT", `/api/dashboard/${dashboardId}`, {
-            dashcards: [
-              {
-                id: -1,
-                card_id: questionId,
-                // Add sane defaults for the dashboard card size
-                row: 0,
-                col: 0,
-                size_x: 11,
-                size_y: 6,
-                ...cardDetails,
-              },
-            ],
-          }).then(response => ({
-            ...response,
-            body: response.body.dashcards[0],
-            questionId,
-          }));
-        },
-      );
-    });
-  },
-);

e2e/support/commands/api/index.ts

+import {
+  archiveCollection,
+  archiveDashboard,
+  createCollection,
+  createDashboard,
+  createNativeQuestion,
+  createQuestion,
+  createQuestionAndDashboard,
+} from "e2e/support/helpers";
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * @deprecated Use function helper instead, i.e.
+       * ```
+       * import { archiveCollection } from "e2e/support/helpers"
+       * ```
+       */
+      archiveCollection: typeof archiveCollection;
+
+      /**
+       * @deprecated Use function helper instead, i.e.
+       * ```
+       * import { archiveDashboard } from "e2e/support/helpers"
+       * ```
+       */
+      archiveDashboard: typeof archiveDashboard;
+
+      /**
+       * @deprecated Use function helper instead, i.e.
+       * ```
+       * import { createCollection } from "e2e/support/helpers"
+       * ```
+       */
+      createCollection: typeof createCollection;
+
+      /**
+       * @deprecated Use function helper instead, i.e.
+       * ```
+       * import { createDashboard } from "e2e/support/helpers"
+       * ```
+       */
+      createDashboard: typeof createDashboard;
+
+      /**
+       * @deprecated Use function helper instead, i.e.
+       * ```
+       * import { createNativeQuestion } from "e2e/support/helpers"
+       * ```
+       */
+      createNativeQuestion: typeof createNativeQuestion;
+
+      /**
+       * @deprecated Use function helper instead, i.e.
+       * ```
+       * import { createQuestion } from "e2e/support/helpers"
+       * ```
+       */
+      createQuestion: typeof createQuestion;
+
+      /**
+       * @deprecated Use function helper instead, i.e.
+       * ```
+       * import { createQuestionAndDashboard } from "e2e/support/helpers"
+       * ```
+       */
+      createQuestionAndDashboard: typeof createQuestionAndDashboard;
+    }
+  }
+}
+
+Cypress.Commands.add("archiveCollection", archiveCollection);
+Cypress.Commands.add("archiveDashboard", archiveDashboard);
+Cypress.Commands.add("createCollection", createCollection);
+Cypress.Commands.add("createDashboard", createDashboard);
+Cypress.Commands.add("createNativeQuestion", createNativeQuestion);
+Cypress.Commands.add("createQuestion", createQuestion);
+Cypress.Commands.add("createQuestionAndDashboard", createQuestionAndDashboard);

e2e/support/commands/api/question.ts

-import { createNativeQuestion, createQuestion } from "e2e/support/helpers";
-
-declare global {
-  namespace Cypress {
-    interface Chainable {
-      /**
-       * @deprecated Use function helper instead, i.e.
-       * ```
-       * import { createQuestion } from "e2e/support/helpers"
-       * ```
-       */
-      createQuestion: typeof createQuestion;
-
-      /**
-       * @deprecated Use function helper instead, i.e.
-       * ```
-       * import { createNativeQuestion } from "e2e/support/helpers"
-       * ```
-       */
-      createNativeQuestion: typeof createNativeQuestion;
-    }
-  }
-}
-
-Cypress.Commands.add("createQuestion", createQuestion);
-Cypress.Commands.add("createNativeQuestion", createNativeQuestion);

e2e/support/helpers/api/addOrUpdateDashboardCard.ts

+import type {
+  CardId,
+  Dashboard,
+  DashboardCard,
+  DashboardId,
+} from "metabase-types/api";
+
+import { DEFAULT_CARD } from "./updateDashboardCards";
+
+export function addOrUpdateDashboardCard({
+  card_id,
+  dashboard_id,
+  card,
+}: {
+  card_id: CardId;
+  dashboard_id: DashboardId;
+  card: Partial<DashboardCard>;
+}): Cypress.Chainable<Cypress.Response<DashboardCard>> {
+  return cy
+    .request<Dashboard>("PUT", `/api/dashboard/${dashboard_id}`, {
+      dashcards: [
+        {
+          ...DEFAULT_CARD,
+          card_id,
+          ...card,
+        },
+      ],
+    })
+    .then(response => ({
+      ...response,
+      body: response.body.dashcards[0],
+    }));
+}

e2e/support/helpers/api/archiveCollection.ts

+import type { CollectionId } from "metabase-types/api";
+
+export const archiveCollection = (id: CollectionId) => {
+  cy.log(`Archiving a collection with id: ${id}`);
+
+  return cy.request("PUT", `/api/collection/${id}`, {
+    archived: true,
+  });
+};

e2e/support/helpers/api/archiveDashboard.ts

+import type { Dashboard, DashboardId } from "metabase-types/api";
+
+export const archiveDashboard = (
+  id: DashboardId,
+): Cypress.Chainable<Cypress.Response<Dashboard>> => {
+  cy.log(`Archiving a dashboard with id: ${id}`);
+
+  return cy.request<Dashboard>("PUT", `/api/dashboard/${id}`, {
+    archived: true,
+  });
+};

e2e/support/helpers/api/archiveQuestion.ts

+import type { Card } from "metabase-types/api";
+
+export const archiveQuestion = (
+  id: Card["id"],
+): Cypress.Chainable<Cypress.Response<Card>> => {
+  cy.log(`Archiving a question with id: ${id}`);
+
+  return cy.request<Card>("PUT", `/api/card/${id}`, {
+    archived: true,
+  });
+};

e2e/support/helpers/api/createCollection.ts

+import type { Collection, RegularCollectionId } from "metabase-types/api";
+
+export const createCollection = ({
+  name,
+  description = null,
+  parent_id = null,
+  authority_level = null,
+}: {
+  name: string;
+  description?: string | null;
+  parent_id?: RegularCollectionId | null;
+  authority_level?: "official" | null;
+}): Cypress.Chainable<Cypress.Response<Collection>> => {
+  cy.log(`Create a collection: ${name}`);
+
+  return cy.request("POST", "/api/collection", {
+    name,
+    description,
+    parent_id,
+    authority_level,
+  });
+};

e2e/support/helpers/api/createDashboard.ts

+import type {
+  CreateDashboardRequest,
+  Dashboard,
+  DashboardCard,
+} from "metabase-types/api";
+
+export interface DashboardDetails extends Omit<CreateDashboardRequest, "name"> {
+  name?: string;
+  auto_apply_filters?: Dashboard["auto_apply_filters"];
+  enable_embedding?: Dashboard["enable_embedding"];
+  embedding_params?: Dashboard["embedding_params"];
+  dashcards?: Partial<DashboardCard>[];
+}
+
+interface Options {
+  /**
+   * Whether to wrap a dashboard id, to make it available outside of this scope.
+   * Defaults to false.
+   */
+  wrapId?: boolean;
+  /**
+   * Alias a dashboard id in order to use it later with `cy.get("@" + alias).
+   * Defaults to "dashboardId".
+   */
+  idAlias?: string;
+}
+
+export const createDashboard = (
+  dashboardDetails: DashboardDetails = {},
+  options: Options = {},
+): Cypress.Chainable<Cypress.Response<Dashboard>> => {
+  const {
+    name = "Test Dashboard",
+    auto_apply_filters,
+    enable_embedding,
+    embedding_params,
+    dashcards,
+    ...restDashboardDetails
+  } = dashboardDetails;
+  const { wrapId = false, idAlias = "dashboardId" } = options;
+
+  cy.log(`Create a dashboard: ${name}`);
+
+  // For all the possible keys, refer to `src/metabase/api/dashboard.clj`
+  return cy
+    .request<Dashboard>("POST", "/api/dashboard", {
+      name,
+      ...restDashboardDetails,
+    })
+    .then(({ body }) => {
+      if (wrapId) {
+        cy.wrap(body.id).as(idAlias);
+      }
+      if (
+        enable_embedding != null ||
+        auto_apply_filters != null ||
+        Array.isArray(dashcards)
+      ) {
+        cy.request<Dashboard>("PUT", `/api/dashboard/${body.id}`, {
+          auto_apply_filters,
+          enable_embedding,
+          embedding_params,
+          dashcards,
+        });
+      }
+    });
+};

e2e/support/helpers/api/createDashboardWithTabs.ts

+import type { Dashboard } from "metabase-types/api";
+
+import { createDashboard, type DashboardDetails } from "./createDashboard";
+
+export function createDashboardWithTabs({
+  dashcards = [],
+  tabs,
+  ...dashboardDetails
+}: DashboardDetails): Cypress.Chainable<Cypress.Response<Dashboard>> {
+  return createDashboard(dashboardDetails).then(({ body: dashboard }) => {
+    cy.request<Dashboard>("PUT", `/api/dashboard/${dashboard.id}`, {
+      ...dashboard,
+      dashcards,
+      tabs,
+    }).then(({ body: dashboard }) => cy.wrap(dashboard));
+  });
+}

e2e/support/helpers/api/createNativeQuestion.ts

+import { SAMPLE_DB_ID } from "e2e/support/cypress_data";
+import type { Card, DatasetQuery, NativeQuery } from "metabase-types/api";
+
+import {
+  logAction,
+  question,
+  type Options,
+  type QuestionDetails,
+} from "./createQuestion";
+
+export type NativeQuestionDetails = Omit<QuestionDetails, "dataset_query"> & {
+  /**
+   * Defaults to SAMPLE_DB_ID.
+   */
+  database?: DatasetQuery["database"];
+  native: NativeQuery;
+};
+
+export const createNativeQuestion = (
+  questionDetails: NativeQuestionDetails,
+  options?: Options,
+): Cypress.Chainable<Cypress.Response<Card>> => {
+  const { database = SAMPLE_DB_ID, name, native } = questionDetails;
+
+  if (!native) {
+    throw new Error('"native" attribute missing in questionDetails');
+  }
+
+  logAction("Create a native question", name);
+
+  return question(
+    {
+      ...questionDetails,
+      dataset_query: { type: "native", native, database },
+    },
+    options,
+  );
+};

e2e/support/helpers/e2e-question-helpers.ts → e2e/support/helpers/api/createQuestion.ts

 import { SAMPLE_DB_ID } from "e2e/support/cypress_data";
-import type {
-  Card,
-  DatasetQuery,
-  NativeQuery,
-  StructuredQuery,
-} from "metabase-types/api";
+import type { Card, DatasetQuery, StructuredQuery } from "metabase-types/api";
 
-type QuestionDetails = {
+export type QuestionDetails = {
   dataset_query: DatasetQuery;
   /**
    * Defaults to "test question".
@@ -50,15 +45,7 @@ export type StructuredQuestionDetails = Omit<
   query: StructuredQuery;
 };
 
-export type NativeQuestionDetails = Omit<QuestionDetails, "dataset_query"> & {
-  /**
-   * Defaults to SAMPLE_DB_ID.
-   */
-  database?: DatasetQuery["database"];
-  native: NativeQuery;
-};
-
-type Options = {
+export type Options = {
   /**
    * Whether to visit the question in order to load its metadata.
    * Defaults to false.
@@ -107,38 +94,7 @@ export const createQuestion = (
   );
 };
 
-export const createNativeQuestion = (
-  questionDetails: NativeQuestionDetails,
-  options?: Options,
-): Cypress.Chainable<Cypress.Response<Card>> => {
-  const { database = SAMPLE_DB_ID, name, native } = questionDetails;
-
-  if (!native) {
-    throw new Error('"native" attribute missing in questionDetails');
-  }
-
-  logAction("Create a native question", name);
-
-  return question(
-    {
-      ...questionDetails,
-      dataset_query: { type: "native", native, database },
-    },
-    options,
-  );
-};
-
-export const archiveQuestion = (
-  id: Card["id"],
-): Cypress.Chainable<Cypress.Response<Card>> => {
-  cy.log(`Archiving a question with id: ${id}`);
-
-  return cy.request("PUT", `/api/card/${id}`, {
-    archived: true,
-  });
-};
-
-const question = (
+export const question = (
   {
     name = "test question",
     description,
@@ -161,7 +117,7 @@ const question = (
   }: Options = {},
 ) => {
   return cy
-    .request("POST", "/api/card", {
+    .request<Card>("POST", "/api/card", {
       name,
       description,
       dataset_query,
@@ -209,7 +165,7 @@ const question = (
     });
 };
 
-const logAction = (
+export const logAction = (
   /**
    * A title used to log the Cypress action/request that follows it.
    */

e2e/support/helpers/api/createQuestionAndDashboard.ts

+import type { CardId, Dashboard, DashboardCard } from "metabase-types/api";
+
+import { createDashboard, type DashboardDetails } from "./createDashboard";
+import {
+  createQuestion,
+  type StructuredQuestionDetails,
+} from "./createQuestion";
+
+export const createQuestionAndDashboard = ({
+  questionDetails,
+  dashboardDetails,
+  cardDetails,
+}: {
+  questionDetails: StructuredQuestionDetails;
+  dashboardDetails?: DashboardDetails;
+  cardDetails?: Partial<DashboardCard>;
+}): Cypress.Chainable<
+  Cypress.Response<DashboardCard> & { questionId: CardId }
+> => {
+  return createQuestion(questionDetails).then(
+    ({ body: { id: questionId } }) => {
+      return createDashboard(dashboardDetails).then(
+        ({ body: { id: dashboardId } }) => {
+          return cy
+            .request<Dashboard>("PUT", `/api/dashboard/${dashboardId}`, {
+              dashcards: [
+                {
+                  id: -1,
+                  card_id: questionId,
+                  // Add sane defaults for the dashboard card size
+                  row: 0,
+                  col: 0,
+                  size_x: 11,
+                  size_y: 6,
+                  ...cardDetails,
+                },
+              ],
+            })
+            .then(response => ({
+              ...response,
+              body: response.body.dashcards[0],
+              questionId,
+            }));
+        },
+      );
+    },
+  );
+};

e2e/support/helpers/api/index.ts

+export { addOrUpdateDashboardCard } from "./addOrUpdateDashboardCard";
+export { archiveCollection } from "./archiveCollection";
+export { archiveDashboard } from "./archiveDashboard";
+export { archiveQuestion } from "./archiveQuestion";
+export { createApiKey } from "./createApiKey";
+export { createCollection } from "./createCollection";
+export { createDashboard } from "./createDashboard";
+export type { DashboardDetails } from "./createDashboard";
+export { createDashboardWithTabs } from "./createDashboardWithTabs";
+export { createNativeQuestion } from "./createNativeQuestion";
+export type { NativeQuestionDetails } from "./createNativeQuestion";
+export { createQuestion } from "./createQuestion";
+export type {
+  QuestionDetails,
+  StructuredQuestionDetails,
+} from "./createQuestion";
+export { createQuestionAndDashboard } from "./createQuestionAndDashboard";
+export { remapDisplayValueToFK } from "./remapDisplayValueToFK";
+export { updateDashboardCards } from "./updateDashboardCards";

e2e/support/helpers/api/updateDashboardCards.ts

+import type { Dashboard, DashboardCard, DashboardId } from "metabase-types/api";
+
+export const DEFAULT_CARD = {
+  id: -1,
+  row: 0,
+  col: 0,
+  size_x: 11,
+  size_y: 8,
+  visualization_settings: {},
+  parameter_mappings: [],
+};
+
+/**
+ * Replaces all the cards on a dashboard with the array given in the `cards` parameter.
+ * Can be used to remove cards (exclude from array), or add/update them.
+ */
+export function updateDashboardCards({
+  dashboard_id,
+  cards,
+}: {
+  dashboard_id: DashboardId;
+  cards: Partial<DashboardCard>[];
+}): Cypress.Chainable<Cypress.Response<Dashboard>> {
+  let id = -1;
+  return cy.request<Dashboard>("PUT", `/api/dashboard/${dashboard_id}`, {
+    dashcards: cards.map(card => ({ ...DEFAULT_CARD, id: id--, ...card })),
+  });
+}

e2e/support/helpers/e2e-collection-helpers.ts

@@ -5,40 +5,7 @@ import {
   getFullName,
   popover,
 } from "e2e/support/helpers";
-import type {
-  Collection,
-  CollectionId,
-  RegularCollectionId,
-} from "metabase-types/api";
-
-export const createCollection = ({
-  name,
-  description = null,
-  parent_id = null,
-  authority_level = null,
-}: {
-  name: string;
-  description?: string | null;
-  parent_id?: RegularCollectionId | null;
-  authority_level?: "official" | null;
-}): Cypress.Chainable<Cypress.Response<Collection>> => {
-  cy.log(`Create a collection: ${name}`);
-
-  return cy.request("POST", "/api/collection", {
-    name,
-    description,
-    parent_id,
-    authority_level,
-  });
-};
-
-export const archiveCollection = (id: CollectionId) => {
-  cy.log(`Archiving a collection with id: ${id}`);
-
-  return cy.request("PUT", `/api/collection/${id}`, {
-    archived: true,
-  });
-};
+import type { CollectionId } from "metabase-types/api";
 
 /**
  * Clicks the "+" icon on the collection page and selects one of the menu options