@servicetitan/docs-anvil-uikit-contrib 25.4.1 → 25.6.0

package/docs/testing-library/01-api.mdx

@@ -0,0 +1,250 @@
+---
+title: API
+---
+
+## MockApiCalls
+
+When it isn't practical to [mock the API service classes](frontend/unit-testing#migrating-from-autogenerated-api-mocks), use `MockApiCalls` to configure responses for API endpoints.
+
+```ts
+describe('[admin] AppRoutes', () => {
+    // Create helper to mock API calls
+    const apiResponses = MockApiCalls();
+
+    beforeEach(() => {
+        apiResponses.reset();
+        // Configure /Admin/isGoEnvironment to return false
+        apiResponses.add(/Admin\/isGoEnvironment/, { body: () => false });
+    });
+
+    describe('when user is not authorized', () => {
+        // Configure /Admin/GetClientData to return 401 Unauthorized
+        beforeEach(() => apiResponses.add(/Admin\/GetClientData/, { status: 401 }));
+    });
+});
+```
+
+It exposes the following methods:
+
+-   [add](#add): Configure an API response
+-   [replace](#replace): Replace a previously configured response
+-   [reset](#reset): Remove all previously configured responses
+
+### add
+
+Configure API response.
+
+```ts
+add(
+    path: RegExp,
+    response: {
+        body?: (url: string) => any,
+        status?: number,
+    }
+)
+```
+
+-   `path`: regular expression to match against GET request URLs. If a URL matches more than one path, the first one wins.
+-   `body`: function that returns the API response. If omitted, or if it returns `undefined`, the mock returns an empty object (`{}`).
+-   `status`: HTTP status code for API response. Defaults to 200.
+
+```ts
+// Configure GET /desktop/version.json to return test clientVersion
+apiResponses.add(/desktop\/version\.json/, { body: () => ({ clientVersion }) });
+
+// Configure GET /Admin/GetClientData to return 401 status
+apiResponses.add(/Admin\/GetClientData/, { status: 401 });
+```
+
+**Note:** `MockApiCalls` passes the request URL to the `body` function so that it can customize the return value based on query params or other attributes. This also facilitates logging API calls for debugging purposes.
+
+```ts
+// Log all API calls
+apiResponses.add(/.*/, { body: (url: string) => console.log(`GET ${url}`) });
+```
+
+### replace
+
+Replace a previously configured API response.
+
+```ts
+replace(
+    path: RegExp,
+    response: {
+        body?: (url: string) => any,
+        status?: number,
+    }
+)
+```
+
+-   `path`: the exact regular expression to replace
+-   `response`: see [add](#add)
+
+The `path` must exactly match a previously configured API response. Otherwise, the function does nothing.
+
+```ts
+// Change GET /Admin/GetClientData to return 403 status
+apiResponses.replace(/Admin\/GetClientData/, { status: 403 });
+```
+
+### reset
+
+Remove all previously configured responses.
+
+```ts
+apiResponses.reset();
+```
+
+## mockComponent
+
+Use `mockComponent` with `jest.mock` to replace a React component with a stub that renders a placeholder instead of the actual component. Test cans then use the [`toContainComponent`](./matchers/#tocontaincomponent) matcher to confirm the component was rendered correctly.
+
+```ts
+mockComponent(
+    name: string,
+    options?: {
+        renderChildren?: boolean = false,
+        renderProps?: boolean = true,
+        forwardRef?: boolean = false,
+    }
+)
+```
+
+-   `renderChildren`: Set to `true` to render both the component and it's children Defaults to `false`.
+-   `renderProps`: Set to `true` to render the component's props. Defaults to `true`.
+-   `forwardRef`: Set to `true` when mocking a component that is wrapped within `React.forwardRef`. Defaults to `false`.
+
+```ts
+// Replace <BillingNewAdmin> component with placeholder
+jest.mock('../modules/billing/components/billing-new-admin', () =>
+    mockComponent('BillingNewAdmin')
+);
+
+// Check that placeholder was rendered
+expect(screen).toContainComponent('BillingNewAdmin');
+```
+
+## mockLocation
+
+Use `mockLocation` to change or mock `window.location`.
+
+```ts
+mockLocation(
+    newLocation: string | {
+        origin?: string,
+        pathname?: string,
+    }
+)
+```
+
+When called with a string, it sets `location.pathname`.
+
+Use the object signature to change either or both `location.origin` and `location.pathname`.
+
+-   `origin`: new `location.origin`. Defaults to preserving previous value.
+-   `pathname`: new `location.pathname`. Defaults to preserving previous value.
+
+To mock `window.location` without changing the value, pass an empty object.
+
+```ts
+// Change location.pathname to "/login" (location.origin remains unchanged)
+mockLocation('/login');
+
+// Change location.origin to "https//jest.st.dev" (location.pathname remains unchanged)
+mockLocation({ origin: 'https://jest.st.dev' });
+
+// Enable spying on window.location
+mockLocation({});
+// ...
+expect(window.location.reload).toHaveBeenCalled();
+```
+
+## mockStyles
+
+Use `mockStyles` with `jest.mock` to mock imported CSS styles.
+
+```ts
+// Mock CSS styles
+jest.mock('../header.module.less', () => mockStyles());
+import * as Styles from '../header.module.less';
+
+// Check that style was rendered
+expect(screen).toContainComponent('Header', { className: Styles.header });
+```
+
+## mockWithDefaultLayout
+
+Use `mockWithDefaultLayout` with `jest.mock` to mock `withDefaultLayout`.
+
+```ts
+jest.mock('../modules/common/components/default-layout', () => ({
+    withDefaultLayout: mockWithDefaultLayout(),
+    ...mockComponent('DefaultLayout'),
+}));
+```
+
+## renderHookWithProvider
+
+Use `renderHookWithProvider` to [render a hook](https://react-hooks-testing-library.com/reference/api#renderhook) within a `<Provider>` wrapper with the specified singletons.
+
+```ts
+renderHookWithProvider<TProps, TResult>(
+    singletons: ProviderProps['singletons'],
+    callback: (props: TProps) => TResult,
+    options?: RenderHookOptions<TProps>
+)
+```
+
+```ts
+const subject = () => {
+    const { result } = renderHookWithProvider(
+        [
+            { provide: MainAppStore, useValue: mainAppStore },
+            { provide: AppUserStore, useValue: appUserStore },
+            { provide: FeatureStore, useValue: featureStore },
+        ],
+        () => useTenantName()
+    );
+    return result.current;
+};
+```
+
+## setupApp
+
+Use `setupApp` to mock the Monolith's global `window.App` state. It restores `window.App` to a clean state before applying the specified values.
+
+To preserve the previous state, spread `window.App` into the argument.
+
+```ts
+setupApp({
+    [key: string]: Record<string, any> | undefined;
+    AppUser?: Record<string, any>;
+    Data?: Record<string, any>;
+    Enum?: Record<string, any>;
+    Features?: Record<string, any>;
+    Permissions?: Record<string, any>;
+    Services?: Record<string, any>;
+    UserNotifications?: Record<string, any>;
+    Utils?: Record<string, any>;
+})
+```
+
+```ts
+// Mock window.App.IsSandboxedProductionInstance and window.App.IsStageInstance
+// (resets other attributes to initial state)
+setupApp({ IsSandboxedProductionInstance: () => false, IsStageInstance: () => false });
+
+// Mock window.App.Features (resets other attributes to initial state)
+beforeEach(() => {
+    setupApp({
+        Features: {
+            EnableDispatchCenter: true,
+            DispatchCenterApiUrl: 'DispatchCenterApiUrl',
+            DispatchCenterMicroFrontendUrl: 'DispatchCenterMicroFrontendUrl',
+        },
+    });
+});
+
+// Mock window.App.LogService and keep previous state of other attributes
+setupApp({ ...window.App, LogService: { error: jest.fn() } });
+```

package/docs/testing-library/02-queries.mdx

@@ -0,0 +1,48 @@
+---
+title: Queries
+---
+
+Testing Library includes custom [queries](https://testing-library.com/docs/queries/about) that find elements with ServiceTitan specific attributes.
+
+## Usage
+
+To use custom queries, import them from Testing Library and merge them with the default set of queries attached to rendered components.
+
+```ts
+import { queries, render } from '@testing-library/react'; // Import default queries
+import { queries as customQueries } from '@servicetitan/testing-library'; // Import custom queries
+
+// ...
+
+const subject = () => {
+    return render(
+        <MyComponent />,
+        // Merge custom queries with defaults
+        { queries: { ...queries, ...customQueries } }
+    );
+};
+```
+
+## ByAnvilComponentName
+
+> getByAnvilComponentName, queryByAnvilComponentName, getAllByAnvilComponentName, queryAllByAnvilComponentName, findByAnvilComponentName, findAllByAnvilComponentName
+
+Searches for all elements that have a node with the `data-anvil-component` attribute and content matching the given `Matcher`.
+
+**Use with caution.** Using Anvil attributes does not resemble how users see the software and should be avoided. Use this only when queries for user-visible attributes (e.g., **ByRole**, **ByText**) don't work.
+
+```ts
+ByAnvilComponentName(
+    container: HTMLElement,
+    id: Matcher,
+    options?: MatcherOptions,
+)
+```
+
+```ts
+// Custom queries are bound to render result
+const { getByAnvilComponentName } = subject();
+
+// Check that subject() rendered Anvil icon with specified class
+expect(getByAnvilComponentName('Icon')).toHaveClass('foo');
+```

package/docs/testing-library/03-matchers.mdx

@@ -0,0 +1,117 @@
+---
+title: Matchers
+---
+
+## toBeWithinRange
+
+Checks whether a value equals another value, plus or minus the specified delta.
+
+```ts
+toBeWithinRange(
+    value: number,
+    delta: number
+)
+```
+
+```ts
+// Check whether actual equals expected ± 0.01
+expect(actual).toBeWithinRange(expect, 0.01);
+```
+
+## toContainAnvilComponent
+
+Checks whether an element contains an Anvil component (see [ByAnvilComponentName](./queries/#byanvilcomponentname)) with the specified name.
+
+**Use with caution.** Using Anvil attributes does not resemble how users see the software and should be avoided. Use this only when queries for user-visible attributes (e.g., **ByRole**, **ByText**) don't work.
+
+```ts
+toContainAnvilComponent(
+    name: string,
+    options?: SelectorMatcherOptions
+)
+```
+
+```ts
+// Check that Anvil Icon component was rendered
+expect(screen).toContainAnvilComponent('Icon');
+```
+
+## toContainClassName
+
+Checks whether an element contains another element with the specified class.
+
+```ts
+toContainClassName(
+    className: string
+)
+```
+
+```ts
+// Check that element with CSS class .in-partner-portal was rendered
+expect(screen).toContainClassName('in-partner-portal');
+```
+
+## toContainComponent
+
+Checks whether an element contains a [mocked component](./api/#mockcomponent) with the specified name and React props.
+
+```ts
+toContainComponent(
+    name: string,
+    props?: Record<string, any>,
+    options?: {
+        exact?: boolean = true,
+    }
+)
+```
+
+-   `name`: the mocked component's name
+-   `props`: props to check were passed to the component
+-   `exact`: controls whether only specified the props are allowed. Defaults to `true`.
+
+```ts
+// Check that <MarketingModule /> was rendered (with no props)
+expect(screen).toContainComponent('MarketingModule');
+
+// Check that <Redirect to="/login" /> was rendered
+expect(screen).toContainComponent('Redirect', { to: '/login' });
+```
+
+To allow partial matches, set `exact` to `false`. For example,
+
+```ts
+// Check that exactly <Tag color="critical" /> was render
+expect(screen).toContainComponent('Tag', { color: 'critical' });
+
+// Check that <Tag /> was rendered with at least color="critical", and possibly other options
+expect(screen).toContainComponent('Tag', { color: 'critical' }, { exact: false });
+
+// Check that <Tag /> was rendered with or without any options
+expect(screen).toContainComponent('Tag', {}, { exact: false });
+```
+
+## toContainText
+
+Checks whether an element contains the specified text.
+
+```ts
+toContainText(
+    text?: string | RegExp,
+    options?: SelectorMatcherOptions,
+)
+```
+
+```ts
+// Check that screen contains instructions to download Chrome
+expect(screen).toContainText(/download.*Chrome/i);
+```
+
+To check whether the element contains any text at all, omit the `text` argument. For example,
+
+```ts
+// Check that any text was rendered
+expect(screen).toContainText();
+
+// Check that no text was rendered
+expect(screen).not.toContainText();
+```

package/docs/testing-library/index.mdx

@@ -0,0 +1,22 @@
+---
+title: Testing Library
+---
+
+`@servicetitan/testing-library` is a light-weight solution for testing ServiceTitan components that builds on top of [`@testing-library/react`](https://testing-library.com/docs/react-testing-library/intro/) and encourages testing best practices.
+
+## Usage
+
+This project should be installed as one of your project's `devDependencies`:
+
+```bash
+npm install --save-dev @servicetitan/testing-library
+```
+
+This library has `peerDependencies` for:
+
+-   `@servicetitan/react-ioc`: >=22.0.0
+-   `@testing-library/react`: ^12.0.0
+-   `@testing-library/react-hooks`: ^7.0.0
+-   `react`: >=17.0.0
+
+**Note:** This library is not compatible with React Testing Library versions 13+.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-anvil-uikit-contrib",
-    "version": "25.4.1",
+    "version": "25.6.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "47af4bd32673af7e0292f1e55316164615135b74"
+    "gitHead": "2adbff52245b96041ba194c5b904a9cb05f0e0e3"
 }