rescript-vitest-extras 0.1.0

package/src/VitestExtras__BrowserLocator.res

@@ -0,0 +1,190 @@
+// =============================================================================
+// Shared Types
+// =============================================================================
+
+/**
+ * Vitest Browser Locator API bindings.
+ *
+ * Provides type-safe bindings for the `@vitest/browser` Locator class, including
+ * query methods (getByRole, getByText, etc.), filtering, interaction, and element access.
+ */
+/** Opaque type for the Locator object from `@vitest/browser`. */
+type t
+
+/** ARIA role, typed as string since the set is large and extensible. */
+type ariaRole = string
+
+/** Represents `string | RegExp` in the JS API. Zero-cost via `@unboxed`. */
+@unboxed
+type stringOrRegExp = String(string) | RegExp(RegExp.t)
+
+// =============================================================================
+// Options Types
+// =============================================================================
+
+/** Options for `getByRole` queries. All fields are optional. */
+type locatorByRoleOptions = {
+  exact?: bool,
+  checked?: bool,
+  disabled?: bool,
+  expanded?: bool,
+  includeHidden?: bool,
+  level?: int,
+  name?: stringOrRegExp,
+  pressed?: bool,
+  selected?: bool,
+}
+
+/** Options for text-based queries and the `filter` method. */
+type locatorFilterOptions = {
+  hasText?: stringOrRegExp,
+  hasNotText?: stringOrRegExp,
+  has?: t,
+  hasNot?: t,
+}
+
+// =============================================================================
+// Escape Hatch
+// =============================================================================
+
+/** Wraps a raw DOM element as a Locator for APIs that accept `Element | Locator` at runtime. */
+external fromElement: Dom.element => t = "%identity"
+
+// =============================================================================
+// Query Methods
+// =============================================================================
+
+/** Returns a locator for the first element matching the given ARIA role. */
+@send
+external getByRole: (t, ariaRole, ~options: locatorByRoleOptions=?) => t = "getByRole"
+
+/** Returns a locator for the first element matching the given text content. */
+@send
+external getByText: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t = "getByText"
+
+/** Returns a locator for the first element matching the given label text. */
+@send
+external getByLabelText: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t =
+  "getByLabelText"
+
+/** Returns a locator for the first element matching the given placeholder text. */
+@send
+external getByPlaceholder: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t =
+  "getByPlaceholder"
+
+/** Returns a locator for the first element matching the given alt text. */
+@send
+external getByAltText: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t = "getByAltText"
+
+/** Returns a locator for the first element matching the given `data-testid` attribute. */
+@send
+external getByTestId: (t, stringOrRegExp) => t = "getByTestId"
+
+/** Returns a locator for the first element matching the given title attribute. */
+@send
+external getByTitle: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t = "getByTitle"
+
+// =============================================================================
+// Filtering Methods
+// =============================================================================
+
+/** Returns a locator for the nth element (0-indexed) matched by this locator. */
+@send
+external nth: (t, int) => t = "nth"
+
+/** Returns a locator for the first element matched by this locator. */
+@send
+external first: t => t = "first"
+
+/** Returns a locator for the last element matched by this locator. */
+@send
+external last: t => t = "last"
+
+/** Returns a locator matching elements that satisfy both this locator and the given locator. */
+@send
+external and_: (t, t) => t = "and"
+
+/** Returns a locator matching elements that satisfy either this locator or the given locator. */
+@send
+external or_: (t, t) => t = "or"
+
+/** Filters the matched elements using the provided options. */
+@send
+external filter: (t, locatorFilterOptions) => t = "filter"
+
+// =============================================================================
+// Interaction Methods
+// =============================================================================
+
+/** Clicks the element. Resolves when the action is complete. */
+@send
+external click: (t, ~options: {..}=?) => promise<unit> = "click"
+
+/** Double-clicks the element. Resolves when the action is complete. */
+@send
+external dblClick: (t, ~options: {..}=?) => promise<unit> = "dblClick"
+
+/** Triple-clicks the element. Resolves when the action is complete. */
+@send
+external tripleClick: (t, ~options: {..}=?) => promise<unit> = "tripleClick"
+
+/** Clears the input element's value. Resolves when the action is complete. */
+@send
+external clear: (t, ~options: {..}=?) => promise<unit> = "clear"
+
+/** Hovers over the element. Resolves when the action is complete. */
+@send
+external hover: (t, ~options: {..}=?) => promise<unit> = "hover"
+
+/** Moves the pointer away from the element. Resolves when the action is complete. */
+@send
+external unhover: (t, ~options: {..}=?) => promise<unit> = "unhover"
+
+/** Types the given text into the input element. Resolves when the action is complete. */
+@send
+external fill: (t, string, ~options: {..}=?) => promise<unit> = "fill"
+
+/** Drags the source element and drops it onto the given target locator. */
+@send
+external dropTo: (t, t, ~options: {..}=?) => promise<unit> = "dropTo"
+
+/** Selects the given options in a `<select>` element. The value type is intentionally
+    polymorphic to support `string`, `array<string>`, `HTMLElement`, or `array<HTMLElement>`. */
+@send
+external selectOptions: (t, 'a, ~options: {..}=?) => promise<unit> = "selectOptions"
+
+/** Takes a screenshot of the element. Resolves with the screenshot path. */
+@send
+external screenshot: (t, ~options: {..}=?) => promise<string> = "screenshot"
+
+// =============================================================================
+// Element Access
+// =============================================================================
+
+/** Returns the matched DOM element, or `None` if no element matches. */
+@send @return(nullable)
+external query: t => option<Dom.element> = "query"
+
+/** Returns the matched DOM element. Throws if no element matches. */
+@send
+external element: t => Dom.element = "element"
+
+/** Returns all matched DOM elements as an array. */
+@send
+external elements: t => array<Dom.element> = "elements"
+
+/** Returns all matched locators as an array. */
+@send
+external all: t => array<t> = "all"
+
+// =============================================================================
+// Properties
+// =============================================================================
+
+/** The CSS selector string for this locator. */
+@get
+external selector: t => string = "selector"
+
+/** The number of elements matched by this locator. */
+@get
+external length: t => int = "length"

package/src/VitestExtras__BrowserLocator.resi

@@ -0,0 +1,190 @@
+// =============================================================================
+// Shared Types
+// =============================================================================
+
+/**
+ * Vitest Browser Locator API bindings.
+ *
+ * Provides type-safe bindings for the `@vitest/browser` Locator class, including
+ * query methods (getByRole, getByText, etc.), filtering, interaction, and element access.
+ */
+/** Opaque type for the Locator object from `@vitest/browser`. */
+type t
+
+/** ARIA role, typed as string since the set is large and extensible. */
+type ariaRole = string
+
+/** Represents `string | RegExp` in the JS API. Zero-cost via `@unboxed`. */
+@unboxed
+type stringOrRegExp = String(string) | RegExp(RegExp.t)
+
+// =============================================================================
+// Options Types
+// =============================================================================
+
+/** Options for `getByRole` queries. All fields are optional. */
+type locatorByRoleOptions = {
+  exact?: bool,
+  checked?: bool,
+  disabled?: bool,
+  expanded?: bool,
+  includeHidden?: bool,
+  level?: int,
+  name?: stringOrRegExp,
+  pressed?: bool,
+  selected?: bool,
+}
+
+/** Options for text-based queries and the `filter` method. */
+type locatorFilterOptions = {
+  hasText?: stringOrRegExp,
+  hasNotText?: stringOrRegExp,
+  has?: t,
+  hasNot?: t,
+}
+
+// =============================================================================
+// Escape Hatch
+// =============================================================================
+
+/** Wraps a raw DOM element as a Locator for APIs that accept `Element | Locator` at runtime. */
+external fromElement: Dom.element => t = "%identity"
+
+// =============================================================================
+// Query Methods
+// =============================================================================
+
+/** Returns a locator for the first element matching the given ARIA role. */
+@send
+external getByRole: (t, ariaRole, ~options: locatorByRoleOptions=?) => t = "getByRole"
+
+/** Returns a locator for the first element matching the given text content. */
+@send
+external getByText: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t = "getByText"
+
+/** Returns a locator for the first element matching the given label text. */
+@send
+external getByLabelText: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t =
+  "getByLabelText"
+
+/** Returns a locator for the first element matching the given placeholder text. */
+@send
+external getByPlaceholder: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t =
+  "getByPlaceholder"
+
+/** Returns a locator for the first element matching the given alt text. */
+@send
+external getByAltText: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t = "getByAltText"
+
+/** Returns a locator for the first element matching the given `data-testid` attribute. */
+@send
+external getByTestId: (t, stringOrRegExp) => t = "getByTestId"
+
+/** Returns a locator for the first element matching the given title attribute. */
+@send
+external getByTitle: (t, stringOrRegExp, ~options: locatorFilterOptions=?) => t = "getByTitle"
+
+// =============================================================================
+// Filtering Methods
+// =============================================================================
+
+/** Returns a locator for the nth element (0-indexed) matched by this locator. */
+@send
+external nth: (t, int) => t = "nth"
+
+/** Returns a locator for the first element matched by this locator. */
+@send
+external first: t => t = "first"
+
+/** Returns a locator for the last element matched by this locator. */
+@send
+external last: t => t = "last"
+
+/** Returns a locator matching elements that satisfy both this locator and the given locator. */
+@send
+external and_: (t, t) => t = "and"
+
+/** Returns a locator matching elements that satisfy either this locator or the given locator. */
+@send
+external or_: (t, t) => t = "or"
+
+/** Filters the matched elements using the provided options. */
+@send
+external filter: (t, locatorFilterOptions) => t = "filter"
+
+// =============================================================================
+// Interaction Methods
+// =============================================================================
+
+/** Clicks the element. Resolves when the action is complete. */
+@send
+external click: (t, ~options: {..}=?) => promise<unit> = "click"
+
+/** Double-clicks the element. Resolves when the action is complete. */
+@send
+external dblClick: (t, ~options: {..}=?) => promise<unit> = "dblClick"
+
+/** Triple-clicks the element. Resolves when the action is complete. */
+@send
+external tripleClick: (t, ~options: {..}=?) => promise<unit> = "tripleClick"
+
+/** Clears the input element's value. Resolves when the action is complete. */
+@send
+external clear: (t, ~options: {..}=?) => promise<unit> = "clear"
+
+/** Hovers over the element. Resolves when the action is complete. */
+@send
+external hover: (t, ~options: {..}=?) => promise<unit> = "hover"
+
+/** Moves the pointer away from the element. Resolves when the action is complete. */
+@send
+external unhover: (t, ~options: {..}=?) => promise<unit> = "unhover"
+
+/** Types the given text into the input element. Resolves when the action is complete. */
+@send
+external fill: (t, string, ~options: {..}=?) => promise<unit> = "fill"
+
+/** Drags the source element and drops it onto the given target locator. */
+@send
+external dropTo: (t, t, ~options: {..}=?) => promise<unit> = "dropTo"
+
+/** Selects the given options in a `<select>` element. The value type is intentionally
+    polymorphic to support `string`, `array<string>`, `HTMLElement`, or `array<HTMLElement>`. */
+@send
+external selectOptions: (t, 'a, ~options: {..}=?) => promise<unit> = "selectOptions"
+
+/** Takes a screenshot of the element. Resolves with the screenshot path. */
+@send
+external screenshot: (t, ~options: {..}=?) => promise<string> = "screenshot"
+
+// =============================================================================
+// Element Access
+// =============================================================================
+
+/** Returns the matched DOM element, or `None` if no element matches. */
+@send @return(nullable)
+external query: t => option<Dom.element> = "query"
+
+/** Returns the matched DOM element. Throws if no element matches. */
+@send
+external element: t => Dom.element = "element"
+
+/** Returns all matched DOM elements as an array. */
+@send
+external elements: t => array<Dom.element> = "elements"
+
+/** Returns all matched locators as an array. */
+@send
+external all: t => array<t> = "all"
+
+// =============================================================================
+// Properties
+// =============================================================================
+
+/** The CSS selector string for this locator. */
+@get
+external selector: t => string = "selector"
+
+/** The number of elements matched by this locator. */
+@get
+external length: t => int = "length"

package/src/VitestExtras__BrowserPage.res

@@ -0,0 +1,119 @@
+// =============================================================================
+// Page Singleton
+// =============================================================================
+
+/**
+ * Vitest Browser Page API bindings.
+ *
+ * Wraps the `page` singleton from `vitest/browser` with ergonomic ReScript
+ * convenience functions. Each query method mirrors the corresponding method
+ * on `VitestExtras__BrowserLocator.t` but operates on the top-level page context.
+ */
+/** Abstract type for the Page object from `vitest/browser`. */
+type t
+
+@module("vitest/browser") @val external page: t = "page"
+
+// =============================================================================
+// Query Methods
+// =============================================================================
+
+@send
+external getByRoleBinding: (
+  t,
+  VitestExtras__BrowserLocator.ariaRole,
+  ~options: VitestExtras__BrowserLocator.locatorByRoleOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByRole"
+
+/** Returns a locator for the first element matching the given ARIA role. */
+@inline
+let getByRole = (~options=?, role) => page->getByRoleBinding(role, ~options?)
+
+@send
+external getByTextBinding: (
+  t,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByText"
+
+/** Returns a locator for the first element matching the given text content. */
+@inline
+let getByText = (~options=?, text) => page->getByTextBinding(text, ~options?)
+
+@send
+external getByLabelTextBinding: (
+  t,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByLabelText"
+
+/** Returns a locator for the first element matching the given label text. */
+@inline
+let getByLabelText = (~options=?, text) => page->getByLabelTextBinding(text, ~options?)
+
+@send
+external getByPlaceholderBinding: (
+  t,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByPlaceholder"
+
+/** Returns a locator for the first element matching the given placeholder text. */
+@inline
+let getByPlaceholder = (~options=?, text) => page->getByPlaceholderBinding(text, ~options?)
+
+@send
+external getByAltTextBinding: (
+  t,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByAltText"
+
+/** Returns a locator for the first element matching the given alt text. */
+@inline
+let getByAltText = (~options=?, text) => page->getByAltTextBinding(text, ~options?)
+
+@send
+external getByTestIdBinding: (
+  t,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+) => VitestExtras__BrowserLocator.t = "getByTestId"
+
+/** Returns a locator for the first element matching the given `data-testid` attribute. */
+@inline
+let getByTestId = testId => page->getByTestIdBinding(testId)
+
+@send
+external getByTitleBinding: (
+  t,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+) => VitestExtras__BrowserLocator.t = "getByTitle"
+
+/** Returns a locator for the first element matching the given title attribute. */
+@inline
+let getByTitle = (~options=?, text) => page->getByTitleBinding(text, ~options?)
+
+// =============================================================================
+// Additional Methods
+// =============================================================================
+
+@send external viewportBinding: (t, int, int) => promise<unit> = "viewport"
+
+/** Sets the iframe viewport size. */
+@inline
+let viewport = (width, height) => page->viewportBinding(width, height)
+
+@send external screenshotBinding: (t, ~options: {..}=?) => promise<string> = "screenshot"
+
+/** Takes a screenshot of the current page. Resolves with the screenshot path. */
+@inline
+let screenshot = (~options=?) => page->screenshotBinding(~options?)
+
+@send
+external elementLocatorBinding: (t, Dom.element) => VitestExtras__BrowserLocator.t =
+  "elementLocator"
+
+/** Wraps a DOM element in a Locator. */
+@inline
+let elementLocator = element => page->elementLocatorBinding(element)

package/src/VitestExtras__BrowserPage.resi

@@ -0,0 +1,62 @@
+/**
+ * Vitest Browser Page API bindings.
+ *
+ * Wraps the `page` singleton from `vitest/browser` with ergonomic ReScript
+ * convenience functions. Each query method mirrors the corresponding method
+ * on `VitestExtras__BrowserLocator.t` but operates on the top-level page context.
+ */
+/** Returns a locator for the first element matching the given ARIA role. */
+let // =============================================================================
+// Query Methods
+// =============================================================================
+
+getByRole: (
+  ~options: VitestExtras__BrowserLocator.locatorByRoleOptions=?,
+  VitestExtras__BrowserLocator.ariaRole,
+) => VitestExtras__BrowserLocator.t
+
+/** Returns a locator for the first element matching the given text content. */
+let getByText: (
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+) => VitestExtras__BrowserLocator.t
+
+/** Returns a locator for the first element matching the given label text. */
+let getByLabelText: (
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+) => VitestExtras__BrowserLocator.t
+
+/** Returns a locator for the first element matching the given placeholder text. */
+let getByPlaceholder: (
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+) => VitestExtras__BrowserLocator.t
+
+/** Returns a locator for the first element matching the given alt text. */
+let getByAltText: (
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+) => VitestExtras__BrowserLocator.t
+
+/** Returns a locator for the first element matching the given `data-testid` attribute. */
+let getByTestId: VitestExtras__BrowserLocator.stringOrRegExp => VitestExtras__BrowserLocator.t
+
+/** Returns a locator for the first element matching the given title attribute. */
+let getByTitle: (
+  ~options: VitestExtras__BrowserLocator.locatorFilterOptions=?,
+  VitestExtras__BrowserLocator.stringOrRegExp,
+) => VitestExtras__BrowserLocator.t
+
+// =============================================================================
+// Additional Methods
+// =============================================================================
+
+/** Sets the iframe viewport size. */
+let viewport: (int, int) => promise<unit>
+
+/** Takes a screenshot of the current page. Resolves with the screenshot path. */
+let screenshot: (~options: {..}=?) => promise<string>
+
+/** Wraps a DOM element in a Locator. */
+let elementLocator: Dom.element => VitestExtras__BrowserLocator.t