@okta/odyssey-react-mui 1.22.0 → 1.23.0

package/src/test-selectors/getByQuerySelector.ts

@@ -0,0 +1,176 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import {
+  queries,
+  within,
+  type BoundFunctions,
+  type ByRoleMatcher,
+  type ByRoleOptions,
+  type Matcher,
+  type SelectorMatcherOptions,
+} from "@testing-library/dom";
+
+export type RoleSelectorMethod = "ByRole";
+
+export type TextSelectorMethod =
+  | "ByLabelText"
+  | "ByPlaceholderText"
+  | "ByText"
+  | "ByAltText"
+  | "ByTitle";
+
+export type QueryMethod = "find" | "get" | "query";
+
+export type ByRoleMethods =
+  | "getByRole"
+  // | "getAllByRole"
+  | "queryByRole";
+// | "queryAllByRole"
+// | "findByRole"
+// | "findAllByRole"
+
+export type ByTextMethods =
+  | "getByLabelText"
+  // | "getAllByLabelText"
+  | "queryByLabelText"
+  // | "queryAllByLabelText"
+  // | "findByLabelText"
+  // | "findAllByLabelText"
+  | "getByPlaceholderText"
+  // | "getAllByPlaceholderText"
+  | "queryByPlaceholderText"
+  // | "queryAllByPlaceholderText"
+  // | "findByPlaceholderText"
+  // | "findAllByPlaceholderText"
+  | "getByText"
+  // | "getAllByText"
+  | "queryByText"
+  // | "queryAllByText"
+  // | "findByText"
+  // | "findAllByText"
+  | "getByAltText"
+  // | "getAllByAltText"
+  | "queryByAltText"
+  // | "queryAllByAltText"
+  // | "findByAltText"
+  // | "findAllByAltText"
+  | "getByTitle"
+  // | "getAllByTitle"
+  | "queryByTitle";
+// | "queryAllByTitle"
+// | "findByTitle"
+// | "findAllByTitle"
+
+export const executeTestingLibraryMethod = <
+  CanvasMethods extends keyof BoundFunctions<typeof queries>,
+>({
+  canvas,
+  queryMethod,
+  selectionMethod,
+}: {
+  canvas: Pick<BoundFunctions<typeof queries>, CanvasMethods>;
+  queryMethod: QueryMethod;
+  selectionMethod: RoleSelectorMethod | TextSelectorMethod;
+}) =>
+  canvas[
+    queryMethod.concat(selectionMethod) as keyof Pick<
+      BoundFunctions<typeof queries>,
+      CanvasMethods
+    >
+  ];
+
+export const getByQuerySelector = <
+  LocalQueryMethod extends QueryMethod = "get",
+>({
+  element,
+  queryMethod,
+  queryOptions,
+  role,
+  selectionMethod,
+  text,
+}: {
+  element: HTMLElement;
+  queryMethod: LocalQueryMethod;
+} & (
+  | {
+      queryOptions?: ByRoleOptions;
+      role: ByRoleMatcher;
+      selectionMethod: RoleSelectorMethod;
+      text?: never;
+    }
+  | {
+      queryOptions?: SelectorMatcherOptions;
+      role?: never;
+      selectionMethod: TextSelectorMethod;
+      text: Matcher;
+    }
+)) => {
+  const canvas = within(element);
+
+  const capturedElement =
+    selectionMethod === "ByRole"
+      ? executeTestingLibraryMethod<ByRoleMethods>({
+          canvas,
+          queryMethod,
+          selectionMethod,
+        })(role, queryOptions)
+      : executeTestingLibraryMethod<ByTextMethods>({
+          canvas,
+          queryMethod,
+          selectionMethod,
+        })(text, queryOptions);
+
+  return capturedElement as LocalQueryMethod extends "get"
+    ? HTMLElement
+    : HTMLElement | null;
+};
+
+export const getByRoleQuerySelector = <LocalQueryMethod extends QueryMethod>({
+  element,
+  queryMethod,
+  queryOptions,
+  role,
+}: {
+  element: HTMLElement;
+  queryMethod: LocalQueryMethod;
+  queryOptions?: ByRoleOptions;
+  role: ByRoleMatcher;
+}) =>
+  getByQuerySelector({
+    element,
+    queryMethod,
+    queryOptions,
+    role,
+    selectionMethod: "ByRole",
+  });
+
+export const getByTextQuerySelector = <LocalQueryMethod extends QueryMethod>({
+  element,
+  queryMethod,
+  queryOptions,
+  selectionMethod,
+  text,
+}: {
+  element: HTMLElement;
+  queryMethod: LocalQueryMethod;
+  queryOptions?: SelectorMatcherOptions;
+  selectionMethod: TextSelectorMethod;
+  text: Matcher;
+}) =>
+  getByQuerySelector({
+    element,
+    queryMethod,
+    queryOptions,
+    selectionMethod,
+    text,
+  });

package/src/test-selectors/getComputedAccessibleErrorMessageText.ts

@@ -0,0 +1,52 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import { normalizeText, validateHtmlElement } from "./sanityChecks";
+
+// Code modified from: https://github.com/testing-library/jest-dom/blob/main/src/to-have-accessible-errormessage.js
+
+/** @see https://www.w3.org/TR/wai-aria-1.2/#aria-errormessage */
+export const getComputedAccessibleErrorMessageText = (
+  htmlElement: HTMLElement,
+) => {
+  validateHtmlElement(htmlElement);
+
+  const ariaErrorMessageId = htmlElement.getAttribute("aria-errormessage");
+
+  // `aria-errormessage` only supports a single `id`.
+  if (Boolean(ariaErrorMessageId) && /\s+/.test(ariaErrorMessageId || "")) {
+    throw new Error(
+      "`aria-errormessage` needs to have a single `id`.".concat(
+        "\n",
+        `Received: ${ariaErrorMessageId}`,
+      ),
+    );
+  }
+
+  /** @see https://www.w3.org/TR/wai-aria-1.2/#aria-invalid */
+  const ariaInvalid = htmlElement.getAttribute("aria-invalid");
+
+  // `aria-invalid` only supports `true` when getting an error message.
+  if (!htmlElement.hasAttribute("aria-invalid") || ariaInvalid === "false") {
+    throw new Error(
+      "`aria-invalid` must be `true` when getting an accessible error message.".concat(
+        "\n",
+        `Received: ${ariaInvalid}`,
+      ),
+    );
+  }
+
+  return normalizeText(
+    htmlElement.ownerDocument.getElementById(ariaErrorMessageId || "")
+      ?.textContent ?? "",
+  );
+};

package/src/test-selectors/getComputedAccessibleText.ts

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import {
+  computeAccessibleName,
+  computeAccessibleDescription,
+} from "dom-accessibility-api";
+
+import { type AccessibleTextSelectorValue } from "./testSelector";
+import { getComputedAccessibleErrorMessageText } from "./getComputedAccessibleErrorMessageText";
+
+export const accessibleTextSelector = {
+  description: computeAccessibleDescription,
+  errorMessage: getComputedAccessibleErrorMessageText,
+  label: computeAccessibleName,
+} as const satisfies Record<
+  AccessibleTextSelectorValue,
+  (element: HTMLElement) => string
+>;
+
+export const getComputedAccessibleText = ({
+  element,
+  type,
+}: {
+  element: HTMLElement;
+  type: AccessibleTextSelectorValue;
+}) => accessibleTextSelector[type](element);

package/src/test-selectors/index.ts

@@ -10,6 +10,6 @@
  * See the License for the specific language governing permissions and limitations under the License.
  */
 
-export * from "./featureTestSelector";
+export * from "./queryOdysseySelector";
 export * from "./querySelector";
-export * from "./odysseyTestSelectors";
+export * from "./testSelector";

package/src/test-selectors/interpolateString.ts

@@ -0,0 +1,41 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+export const isRegExpString = (string: string) => /^\/*(.+)\/$/.test(string);
+
+/** @deprecated This function is only to be used to interpolate strings in unit tests. It uses `eval` internally which could be unsafe if it wasn't done explicitly in our testing environment. */
+export const interpolateString = (
+  string: string,
+  replacements: Record<string, string | RegExp>,
+) => {
+  // Writes out all replacement pairs as "const variableName = value" because we don't know which we want. Then at the end, we `return` the value we want by simply adding it as the last thing in eval'd code.
+  const interpolatedString = eval(`
+    ${Object.entries(replacements)
+      .map(
+        ([variableName, value]) =>
+          `const ${variableName} = ${
+            typeof value === "string" ? JSON.stringify(value) : value
+          };`,
+      )
+      .join("")}
+
+    \`${string}\`
+  `) as string;
+
+  if (isRegExpString(interpolatedString)) {
+    // If this string matches the RegExp format, we know that it's a RegExp, and we'll evaluate it to one. TypeScript has no way of knowing the resulting type, so we have to set that ourselves.
+    return eval(interpolatedString) as RegExp;
+  }
+
+  // This interpolated string is just a string.
+  return interpolatedString;
+};

package/src/test-selectors/linkedHtmlSelectors.ts

@@ -0,0 +1,73 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import { type AriaRole } from "react";
+import { ElementError } from "./sanityChecks";
+import { getRole } from "dom-accessibility-api";
+
+/**
+ * For `aria-haspopup`:
+ * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup
+ * For `datalist`:
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist
+ */
+export const getControlledElement = ({
+  element,
+  role,
+}: {
+  element: HTMLElement;
+  /** If this element controls multiple items, it might be valuable to help narrow down the specific item's `role`. */
+  role?: AriaRole;
+}) => {
+  if (element instanceof HTMLInputElement && element.list) {
+    return element.list;
+  }
+
+  if (element.getAttribute("aria-expanded") === "false") {
+    throw new ElementError(
+      "Popup isn't open in ARIA; therefore, it cannot be captured.",
+      element,
+    );
+  }
+
+  const linkedElementIds =
+    element.getAttribute("aria-controls") || element.getAttribute("aria-owns");
+
+  if (!linkedElementIds) {
+    throw new ElementError(
+      "Popup isn't linked; therefore, it cannot be captured.",
+      element,
+    );
+  }
+
+  const linkedElement = linkedElementIds
+    .split(" ")
+    .map((linkedElementId) =>
+      element.ownerDocument.getElementById(linkedElementId),
+    )
+    // This can be `.filter(Boolean)` when Inferred Type Predicates is in TypeScript (which should be part of the version we're using): https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#:~:text=Inferred%20Type%20Predicates,Thanks%20Dan!
+    .filter((linkedElement): linkedElement is HTMLElement =>
+      Boolean(linkedElement),
+    )
+    .find((linkedElement) =>
+      role ? getRole(linkedElement) === role : Boolean(linkedElement),
+    );
+
+  if (!linkedElement) {
+    throw new ElementError(
+      "Controlled element isn't available; therefore, it cannot be captured.",
+      element,
+    );
+  }
+
+  return linkedElement;
+};

package/src/test-selectors/queryOdysseySelector.ts

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) 2024-present, Okta, Inc. and/or its affiliates. All rights reserved.
+ * The Okta software accompanied by this notice is provided pursuant to the Apache License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import { querySelector } from "./querySelector";
+import { type TestSelector } from "./testSelector";
+import { AutocompleteTestSelector } from "../Autocomplete";
+import { CalloutTestSelector } from "../Callout";
+import { SelectTestSelector } from "../Select";
+import { TabsTestSelector } from "../Tabs";
+import { TextFieldTestSelector } from "../TextField";
+
+export const odysseyTestSelector = {
+  Autocomplete: AutocompleteTestSelector,
+  Callout: CalloutTestSelector,
+  Select: SelectTestSelector,
+  Tabs: TabsTestSelector,
+  TextField: TextFieldTestSelector,
+} as const satisfies Record<string, TestSelector>;
+
+export const queryOdysseySelector = <
+  ComponentName extends keyof typeof odysseyTestSelector,
+>(
+  /**
+   * Name of the component you want to select within.
+   */
+  componentName: ComponentName,
+) => querySelector(odysseyTestSelector[componentName]);