Mimic

Katana combinators for running headless browser tests with Puppeteer.

Mimic provides a set of stack-based combinators, powered by Katana, for orchestrating browser interactions using Puppeteer. It enables clear, declarative browser automation and testing by treating the browser session as a composable flow of operations.

import { pipe } from "@dashkite/joy/function"
import * as K from "@dashkite/katana"
import Mimic from "@dashkite/mimic"

await do pipe [
  Mimic.browser
  Mimic.context
  Mimic.page
  Mimic.goto "https://example.com"
  Mimic.select "h1"
  Mimic.text
  K.peek ([ title ]) -> assert.equal title, "Example Domain"
]

Features

• Stack-Based Composition: Leverage Katana to build readable browser interaction pipelines.
• Web Component Support: Built-in support for Shadow DOM traversal and waiting for custom element definitions.
• Reporting: Visually rich, color-coded terminal reporting for browser console and page errors.
• Declarative API: Unified interface for navigation, selection, inspection, and interaction.
• Puppeteer Powered: Reliability and performance of the industry-standard headless browser library.

Installation

Install via your favorite package manager:

pnpm add @dashkite/mimic

Usage

Mimic combinators are asynchronous and designed to be used within a Katana-compatible pipeline. They typically operate on a stack containing browser instances, contexts, pages, and element handles.

import Mimic from "@dashkite/mimic"

# Example: Submitting a login form
await do pipe [
  Mimic.browser
  Mimic.page
  Mimic.goto "/login"
  Mimic.select "input[name='username']"
  Mimic.type "alice"
  Mimic.select "form"
  Mimic.submit
]

# Example: Emulating a device
await do pipe [
  Mimic.browser
  Mimic.page
  Mimic.emulate "iphone/15"
  Mimic.goto "https://example.com"
  Mimic.screenshot.image path: "iphone-example.png"
]

# Example: Reporting browser output
await do pipe [
  Mimic.browser
  Mimic.page
  Mimic.console Mimic.report.console
  Mimic.error Mimic.report.error
  Mimic.goto "https://example.com"
]

Other Resources

• Reference: Detailed API documentation for all combinators.
• Recipes: Task-based scenarios for common browser automation patterns.

Status

This software is currently in active development and is not yet suitable for production use. Please report bugs or request features via the repository's issue tracker.