rescript-vitest-extras 0.1.0

package/src/VitestExtras__BrowserReact.res

@@ -0,0 +1,201 @@
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Vitest Browser React API bindings.
+ *
+ * Provides type-safe bindings for `vitest-browser-react`, including `render`,
+ * `renderHook`, `cleanup`, and the `Pure` submodule with `configure`.
+ * The `renderResult` type extends `LocatorSelectors` with query methods,
+ * property accessors, and lifecycle methods.
+ */
+/** The result of rendering a component. Extends Locator with query methods. */
+type renderResult
+
+/** Options for rendering a component. */
+type componentRenderOptions = {
+  container?: Dom.element,
+  baseElement?: Dom.element,
+  wrapper?: React.component<{children: React.element}>,
+}
+
+/** Options for `renderHook`. Extends `componentRenderOptions` with `initialProps`. */
+type renderHookOptions<'props> = {
+  container?: Dom.element,
+  baseElement?: Dom.element,
+  wrapper?: React.component<{children: React.element}>,
+  initialProps?: 'props,
+}
+
+/** The result of rendering a hook. */
+type renderHookResult<'result> = {
+  result: {current: 'result},
+}
+
+// =============================================================================
+// renderResult — Query Methods
+// =============================================================================
+
+/** Returns a locator for the first element matching the given ARIA role. */
+@send
+external getByRole: (
+  renderResult,
+  VitestExtras__BrowserLocator.ariaRole,
+  ~options: VitestExtras__BrowserLocator.locatorByRoleOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByRole"
+
+/** Returns a locator for the first element matching the given text content. */
+@send
+external getByText: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByText"
+
+/** Returns a locator for the first element matching the given label text. */
+@send
+external getByLabelText: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByLabelText"
+
+/** Returns a locator for the first element matching the given placeholder text. */
+@send
+external getByPlaceholder: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByPlaceholder"
+
+/** Returns a locator for the first element matching the given alt text. */
+@send
+external getByAltText: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByAltText"
+
+/** Returns a locator for the first element matching the given `data-testid` attribute. */
+@send
+external getByTestId: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+) => VitestExtras__BrowserLocator.t = "getByTestId"
+
+/** Returns a locator for the first element matching the given title attribute. */
+@send
+external getByTitle: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByTitle"
+
+// =============================================================================
+// renderResult — Property Accessors
+// =============================================================================
+
+/** The container DOM element that the component was rendered into. */
+@get
+external container: renderResult => Dom.element = "container"
+
+/** The base element for queries. Defaults to `document.body`. */
+@get
+external baseElement: renderResult => Dom.element = "baseElement"
+
+/** The root Locator for the rendered output. */
+@get
+external locator: renderResult => VitestExtras__BrowserLocator.t = "locator"
+
+// =============================================================================
+// renderResult — Lifecycle Methods
+// =============================================================================
+
+/** Unmounts the rendered component. */
+@send
+external unmount: renderResult => promise<unit> = "unmount"
+
+/** Re-renders the component with new props by passing a new React element. */
+@send
+external rerender: (renderResult, React.element) => promise<unit> = "rerender"
+
+/** Returns a `DocumentFragment` of the rendered output. */
+@send
+external asFragment: renderResult => Dom.element = "asFragment"
+
+// =============================================================================
+// renderResult — Escape Hatch
+// =============================================================================
+
+/** Casts a `renderResult` to a `VitestExtras__BrowserLocator.t` for use with Locator APIs. */
+external toLocator: renderResult => VitestExtras__BrowserLocator.t = "%identity"
+
+// =============================================================================
+// renderHookResult — Methods (nested to avoid name collisions)
+// =============================================================================
+
+/** Methods on `renderHookResult`. Nested to avoid name collisions with `renderResult` methods. */
+module HookResult = {
+  /** Runs the given callback inside `act()`. */
+  @send
+  external act: (renderHookResult<'result>, unit => promise<unit>) => promise<unit> = "act"
+
+  /** Re-renders the hook with new props. */
+  @send
+  external rerender: (renderHookResult<'result>, 'props) => promise<unit> = "rerender"
+
+  /** Unmounts the rendered hook. */
+  @send
+  external unmount: renderHookResult<'result> => promise<unit> = "unmount"
+}
+
+// =============================================================================
+// Top-level Functions (auto-cleanup via vitest-browser-react)
+// =============================================================================
+
+/** Renders a React element into the DOM and returns a `renderResult`. Uses auto-cleanup. */
+@module("vitest-browser-react")
+external render: (React.element, ~options: componentRenderOptions=?) => promise<renderResult> =
+  "render"
+
+/** Renders a custom hook and returns its result. Uses auto-cleanup. */
+@module("vitest-browser-react")
+external renderHook: (
+  'props => 'result,
+  ~options: renderHookOptions<'props>=?,
+) => promise<renderHookResult<'result>> = "renderHook"
+
+/** Unmounts all rendered components. Normally called automatically after each test. */
+@module("vitest-browser-react")
+external cleanup: unit => promise<unit> = "cleanup"
+
+// =============================================================================
+// Pure Submodule (no auto-cleanup, manual control)
+// =============================================================================
+
+/** Pure exports from `vitest-browser-react/pure`. No auto-cleanup; call `cleanup` manually. */
+module Pure = {
+  /** Configuration options for the React renderer. */
+  type configOptions = {reactStrictMode?: bool}
+
+  /** Renders a React element into the DOM and returns a `renderResult`. No auto-cleanup. */
+  @module("vitest-browser-react/pure")
+  external render: (React.element, ~options: componentRenderOptions=?) => promise<renderResult> =
+    "render"
+
+  /** Renders a custom hook and returns its result. No auto-cleanup. */
+  @module("vitest-browser-react/pure")
+  external renderHook: (
+    'props => 'result,
+    ~options: renderHookOptions<'props>=?,
+  ) => promise<renderHookResult<'result>> = "renderHook"
+
+  /** Unmounts all rendered components. Must be called manually when using `Pure`. */
+  @module("vitest-browser-react/pure")
+  external cleanup: unit => promise<unit> = "cleanup"
+
+  /** Configures the React renderer (e.g., enabling strict mode). */
+  @module("vitest-browser-react/pure")
+  external configure: configOptions => unit = "configure"
+}

package/src/VitestExtras__BrowserReact.resi

@@ -0,0 +1,201 @@
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Vitest Browser React API bindings.
+ *
+ * Provides type-safe bindings for `vitest-browser-react`, including `render`,
+ * `renderHook`, `cleanup`, and the `Pure` submodule with `configure`.
+ * The `renderResult` type extends `LocatorSelectors` with query methods,
+ * property accessors, and lifecycle methods.
+ */
+/** The result of rendering a component. Extends Locator with query methods. */
+type renderResult
+
+/** Options for rendering a component. */
+type componentRenderOptions = {
+  container?: Dom.element,
+  baseElement?: Dom.element,
+  wrapper?: React.component<{children: React.element}>,
+}
+
+/** Options for `renderHook`. Extends `componentRenderOptions` with `initialProps`. */
+type renderHookOptions<'props> = {
+  container?: Dom.element,
+  baseElement?: Dom.element,
+  wrapper?: React.component<{children: React.element}>,
+  initialProps?: 'props,
+}
+
+/** The result of rendering a hook. */
+type renderHookResult<'result> = {
+  result: {current: 'result},
+}
+
+// =============================================================================
+// renderResult — Query Methods
+// =============================================================================
+
+/** Returns a locator for the first element matching the given ARIA role. */
+@send
+external getByRole: (
+  renderResult,
+  VitestExtras__BrowserLocator.ariaRole,
+  ~options: VitestExtras__BrowserLocator.locatorByRoleOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByRole"
+
+/** Returns a locator for the first element matching the given text content. */
+@send
+external getByText: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByText"
+
+/** Returns a locator for the first element matching the given label text. */
+@send
+external getByLabelText: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByLabelText"
+
+/** Returns a locator for the first element matching the given placeholder text. */
+@send
+external getByPlaceholder: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByPlaceholder"
+
+/** Returns a locator for the first element matching the given alt text. */
+@send
+external getByAltText: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByAltText"
+
+/** Returns a locator for the first element matching the given `data-testid` attribute. */
+@send
+external getByTestId: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+) => VitestExtras__BrowserLocator.t = "getByTestId"
+
+/** Returns a locator for the first element matching the given title attribute. */
+@send
+external getByTitle: (
+  renderResult,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByTitle"
+
+// =============================================================================
+// renderResult — Property Accessors
+// =============================================================================
+
+/** The container DOM element that the component was rendered into. */
+@get
+external container: renderResult => Dom.element = "container"
+
+/** The base element for queries. Defaults to `document.body`. */
+@get
+external baseElement: renderResult => Dom.element = "baseElement"
+
+/** The root Locator for the rendered output. */
+@get
+external locator: renderResult => VitestExtras__BrowserLocator.t = "locator"
+
+// =============================================================================
+// renderResult — Lifecycle Methods
+// =============================================================================
+
+/** Unmounts the rendered component. */
+@send
+external unmount: renderResult => promise<unit> = "unmount"
+
+/** Re-renders the component with new props by passing a new React element. */
+@send
+external rerender: (renderResult, React.element) => promise<unit> = "rerender"
+
+/** Returns a `DocumentFragment` of the rendered output. */
+@send
+external asFragment: renderResult => Dom.element = "asFragment"
+
+// =============================================================================
+// renderResult — Escape Hatch
+// =============================================================================
+
+/** Casts a `renderResult` to a `VitestExtras__BrowserLocator.t` for use with Locator APIs. */
+external toLocator: renderResult => VitestExtras__BrowserLocator.t = "%identity"
+
+// =============================================================================
+// renderHookResult — Methods (nested to avoid name collisions)
+// =============================================================================
+
+/** Methods on `renderHookResult`. Nested to avoid name collisions with `renderResult` methods. */
+module HookResult: {
+  /** Runs the given callback inside `act()`. */
+  @send
+  external act: (renderHookResult<'result>, unit => promise<unit>) => promise<unit> = "act"
+
+  /** Re-renders the hook with new props. */
+  @send
+  external rerender: (renderHookResult<'result>, 'props) => promise<unit> = "rerender"
+
+  /** Unmounts the rendered hook. */
+  @send
+  external unmount: renderHookResult<'result> => promise<unit> = "unmount"
+}
+
+// =============================================================================
+// Top-level Functions (auto-cleanup via vitest-browser-react)
+// =============================================================================
+
+/** Renders a React element into the DOM and returns a `renderResult`. Uses auto-cleanup. */
+@module("vitest-browser-react")
+external render: (React.element, ~options: componentRenderOptions=?) => promise<renderResult> =
+  "render"
+
+/** Renders a custom hook and returns its result. Uses auto-cleanup. */
+@module("vitest-browser-react")
+external renderHook: (
+  'props => 'result,
+  ~options: renderHookOptions<'props>=?,
+) => promise<renderHookResult<'result>> = "renderHook"
+
+/** Unmounts all rendered components. Normally called automatically after each test. */
+@module("vitest-browser-react")
+external cleanup: unit => promise<unit> = "cleanup"
+
+// =============================================================================
+// Pure Submodule (no auto-cleanup, manual control)
+// =============================================================================
+
+/** Pure exports from `vitest-browser-react/pure`. No auto-cleanup; call `cleanup` manually. */
+module Pure: {
+  /** Configuration options for the React renderer. */
+  type configOptions = {reactStrictMode?: bool}
+
+  /** Renders a React element into the DOM and returns a `renderResult`. No auto-cleanup. */
+  @module("vitest-browser-react/pure")
+  external render: (React.element, ~options: componentRenderOptions=?) => promise<renderResult> =
+    "render"
+
+  /** Renders a custom hook and returns its result. No auto-cleanup. */
+  @module("vitest-browser-react/pure")
+  external renderHook: (
+    'props => 'result,
+    ~options: renderHookOptions<'props>=?,
+  ) => promise<renderHookResult<'result>> = "renderHook"
+
+  /** Unmounts all rendered components. Must be called manually when using `Pure`. */
+  @module("vitest-browser-react/pure")
+  external cleanup: unit => promise<unit> = "cleanup"
+
+  /** Configures the React renderer (e.g., enabling strict mode). */
+  @module("vitest-browser-react/pure")
+  external configure: configOptions => unit = "configure"
+}

package/src/VitestExtras__BrowserUserEvent.res

@@ -0,0 +1,200 @@
+/**
+ * Vitest Browser UserEvent API bindings.
+ *
+ * These bindings wrap Vitest's browser-mode `userEvent` singleton with ergonomic
+ * ReScript types. Each method is bound via `@send` with a `Binding` suffix, then
+ * re-exported as an `@inline` convenience wrapper that pipes through the global
+ * singleton.
+ */
+/** Abstract type for a UserEvent instance from `vitest/browser`. */
+type t
+
+@module("vitest/browser") @val external userEvent: t = "userEvent"
+
+// =============================================================================
+// Setup
+// =============================================================================
+
+@send external setupBinding: t => t = "setup"
+
+/** Creates a new, independent UserEvent instance. */
+@inline
+let setup = () => userEvent->setupBinding
+
+// =============================================================================
+// Click Operations
+// =============================================================================
+
+@send
+external clickBinding: (t, VitestExtras__BrowserLocator.t, ~options: {..}=?) => promise<unit> =
+  "click"
+
+/** Clicks the given element. */
+@inline
+let click = (~options=?, locator) => userEvent->clickBinding(locator, ~options?)
+
+@send
+external dblClickBinding: (t, VitestExtras__BrowserLocator.t, ~options: {..}=?) => promise<unit> =
+  "dblClick"
+
+/** Double-clicks the given element. */
+@inline
+let dblClick = (~options=?, locator) => userEvent->dblClickBinding(locator, ~options?)
+
+@send
+external tripleClickBinding: (
+  t,
+  VitestExtras__BrowserLocator.t,
+  ~options: {..}=?,
+) => promise<unit> = "tripleClick"
+
+/** Triple-clicks the given element. */
+@inline
+let tripleClick = (~options=?, locator) => userEvent->tripleClickBinding(locator, ~options?)
+
+// =============================================================================
+// Input Operations
+// =============================================================================
+
+@send
+external fillBinding: (t, VitestExtras__BrowserLocator.t, string) => promise<unit> = "fill"
+
+/** Sets the value of an input element. Unlike `type_`, this does not simulate
+    individual keystrokes and has no options parameter. */
+@inline
+let fill = (locator, text) => userEvent->fillBinding(locator, text)
+
+@send
+external typeBinding: (
+  t,
+  VitestExtras__BrowserLocator.t,
+  string,
+  ~options: {..}=?,
+) => promise<unit> = "type"
+
+/** Types text into the given element character by character, simulating real keyboard input.
+    Named `type_` because `type` is a reserved word in ReScript. */
+@inline
+let type_ = (~options=?, locator, text) => userEvent->typeBinding(locator, text, ~options?)
+
+@send
+external clearBinding: (t, VitestExtras__BrowserLocator.t, ~options: {..}=?) => promise<unit> =
+  "clear"
+
+/** Clears the value of the given input element. */
+@inline
+let clear = (~options=?, locator) => userEvent->clearBinding(locator, ~options?)
+
+// =============================================================================
+// Keyboard
+// =============================================================================
+
+@send
+external keyboardBinding: (t, string) => promise<unit> = "keyboard"
+
+/** Sends keyboard input without targeting a specific element.
+    Uses the same key syntax as `@testing-library/user-event`
+    (e.g., `"{Enter}"`, `"{Shift>}A{/Shift}"`). */
+@inline
+let keyboard = text => userEvent->keyboardBinding(text)
+
+@send
+external tabBinding: (t, ~options: {..}=?) => promise<unit> = "tab"
+
+/** Presses the Tab key, optionally with modifier options (e.g., `{"shift": true}`). */
+@inline
+let tab = (~options=?) => userEvent->tabBinding(~options?)
+
+// =============================================================================
+// Hover
+// =============================================================================
+
+@send
+external hoverBinding: (t, VitestExtras__BrowserLocator.t, ~options: {..}=?) => promise<unit> =
+  "hover"
+
+/** Hovers over the given element. */
+@inline
+let hover = (~options=?, locator) => userEvent->hoverBinding(locator, ~options?)
+
+@send
+external unhoverBinding: (t, VitestExtras__BrowserLocator.t, ~options: {..}=?) => promise<unit> =
+  "unhover"
+
+/** Moves the pointer away from the given element. */
+@inline
+let unhover = (~options=?, locator) => userEvent->unhoverBinding(locator, ~options?)
+
+// =============================================================================
+// Selection
+// =============================================================================
+
+@send
+external selectOptionsBinding: (
+  t,
+  VitestExtras__BrowserLocator.t,
+  'a,
+  ~options: {..}=?,
+) => promise<unit> = "selectOptions"
+
+/** Selects the given option(s) in a `<select>` element. The `values` parameter is
+    intentionally polymorphic to support `string`, `array<string>`, `Locator`,
+    `array<Locator>`, `Dom.element`, or `array<Dom.element>`. */
+@inline
+let selectOptions = (~options=?, locator, values) =>
+  userEvent->selectOptionsBinding(locator, values, ~options?)
+
+// =============================================================================
+// File Upload
+// =============================================================================
+
+@send
+external uploadBinding: (t, VitestExtras__BrowserLocator.t, 'a, ~options: {..}=?) => promise<unit> =
+  "upload"
+
+/** Uploads file(s) to an input element. The `files` parameter is intentionally
+    polymorphic to support `string`, `array<string>`, `File`, or `array<File>`. */
+@inline
+let upload = (~options=?, locator, files) => userEvent->uploadBinding(locator, files, ~options?)
+
+// =============================================================================
+// Drag and Drop
+// =============================================================================
+
+@send
+external dragAndDropBinding: (
+  t,
+  VitestExtras__BrowserLocator.t,
+  VitestExtras__BrowserLocator.t,
+  ~options: {..}=?,
+) => promise<unit> = "dragAndDrop"
+
+/** Drags the source element and drops it onto the target element. */
+@inline
+let dragAndDrop = (~options=?, source, target) =>
+  userEvent->dragAndDropBinding(source, target, ~options?)
+
+// =============================================================================
+// Clipboard
+// =============================================================================
+
+@send
+external copyBinding: t => promise<unit> = "copy"
+
+/** Copies the current selection to the clipboard. */
+@inline
+let copy = () => userEvent->copyBinding
+
+@send
+external cutBinding: t => promise<unit> = "cut"
+
+/** Cuts the current selection to the clipboard. */
+@inline
+let cut = () => userEvent->cutBinding
+
+@send
+external pasteBinding: t => promise<unit> = "paste"
+
+/** Pastes the clipboard contents at the current cursor position. */
+@inline
+let paste = () => userEvent->pasteBinding