---
title: magic.lambda.puppeteer
---

The magic.lambda.puppeteer project provides headless Chromium automation slots for Magic using PuppeteerSharp.
It uses an explicit session model: **[puppeteer.connect]** returns a `session_id`, and every other slot requires
that `session_id`. There is no scoped context or `.lambda` usage.

**Thread safety**: This library is **not thread safe**. Do not use the same `session_id` concurrently across threads.

Sessions use sliding expiration. By default they expire after 15 minutes of inactivity, and are always closed after
2 hours total lifetime. A maximum of **5** concurrent sessions is allowed globally per cloudlet.

## [puppeteer.connect]

Launches Chromium, opens a page, and returns a `session_id`.

Arguments:

* `headless` - Boolean. Launch Chromium in headless mode. Defaults to true.
* `executable` - Full path to Chromium/Chrome binary.
* `executable-path` - Alias for `executable`.
* `timeout` - Launch timeout in milliseconds.
* `user-data-dir` - Directory for Chromium user data.
* `args` - Additional Chromium arguments. Each child value is one argument string.
* `timeout-minutes` - Sliding inactivity timeout in minutes. Defaults to 15.
* `max-lifetime-minutes` - Maximum session lifetime in minutes. Defaults to 120.

Examples:

```
puppeteer.connect
```

```
puppeteer.connect
   headless:true
   executable:"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
   timeout:30000
   args
      .:--no-sandbox
      .:--disable-dev-shm-usage
   timeout-minutes:30
   max-lifetime-minutes:120
```

## [puppeteer.close]

Closes the browser and page associated with a session.

Arguments:

* Slot value - Session identifier returned by **[puppeteer.connect]**.

Examples:

```
puppeteer.close:SESSION_ID
```

## [puppeteer.goto]

Navigates to a URL.

Arguments:

* Slot value - Session identifier.
* `url` - URL to navigate to.
* `timeout` - Navigation timeout in milliseconds.
* `wait-until` - One of `load`, `domcontentloaded`, `networkidle0`, `networkidle2`.

Examples:

```
puppeteer.goto:SESSION_ID
   url:"https://ainiro.io"
```

```
puppeteer.goto:SESSION_ID
   url:"https://ainiro.io"
   timeout:30000
   wait-until:networkidle2
```

## [puppeteer.wait-for-url]

Waits until the page URL matches.

Arguments:

* Slot value - Session identifier.
* `url` - URL string to wait for.
* `timeout` - Timeout in milliseconds.

Examples:

```
puppeteer.wait-for-url:SESSION_ID
   url:"https://ainiro.io/contact-us"
```

## [puppeteer.wait-for-selector]

Waits until a selector appears in the DOM.

Arguments:

* Slot value - Session identifier.
* `selector` - CSS selector to wait for.
* `timeout` - Timeout in milliseconds.
* `visible` - Boolean. Require element to be visible.
* `hidden` - Boolean. Require element to be hidden.

Examples:

```
puppeteer.wait-for-selector:SESSION_ID
   selector:"#name"
   visible:true
```

## [puppeteer.click]

Clicks a selector.

Arguments:

* Slot value - Session identifier.
* `selector` - CSS selector to click.
* `button` - Mouse button: `left`, `middle`, or `right`.
* `click-count` - Number of clicks.
* `delay` - Delay between down and up in milliseconds.

Examples:

```
puppeteer.click:SESSION_ID
   selector:"#submit_contact_form_button"
```

```
puppeteer.click:SESSION_ID
   selector:"#submit_contact_form_button"
   click-count:2
```

## [puppeteer.type]

Types text into a selector.

Arguments:

* Slot value - Session identifier.
* `selector` - CSS selector to type into.
* `text` - Text to type.
* `config-key` - Configuration key resolving the text value.
* `delay` - Delay between key presses in milliseconds.

Supply exactly one of `text` or `config-key`.

Examples:

```
puppeteer.type:SESSION_ID
   selector:"#name"
   text:"Thomas Hansen"
```

```
puppeteer.type:SESSION_ID
   selector:"#info"
   text:"Hello from AI agent"
   delay:25
```

```
puppeteer.type:SESSION_ID
   selector:"#password"
   config-key:"magic:secrets:example-password"
```

## [puppeteer.fill]

Clears and types text into a selector.

Arguments:

* Slot value - Session identifier.
* `selector` - CSS selector to fill.
* `text` - Text to type after clearing.
* `config-key` - Configuration key resolving the text value.
* `delay` - Delay between key presses in milliseconds.

Supply exactly one of `text` or `config-key`.

Examples:

```
puppeteer.fill:SESSION_ID
   selector:"#email"
   text:"thomas@gaiasoul.com"
```

```
puppeteer.fill:SESSION_ID
   selector:"#password"
   config-key:"magic:secrets:example-password"
```

## [puppeteer.press]

Presses a key on a selector.

Arguments:

* Slot value - Session identifier.
* `selector` - CSS selector to focus.
* `key` - Key name (for example `Enter`).
* `delay` - Delay in milliseconds.

Examples:

```
puppeteer.press:SESSION_ID
   selector:"#submit_contact_form_button"
   key:Enter
```

## [puppeteer.select]

Selects option values from a selector.

Arguments:

* Slot value - Session identifier.
* `selector` - CSS selector for a `<select>` element.
* `values` - Values to select. Provide as children or a comma-separated string.

Examples:

```
puppeteer.select:SESSION_ID
   selector:"#plan"
   values
      .:basic
      .:pro
```

## [puppeteer.content]

Returns page HTML.

Arguments:

* Slot value - Session identifier.

Examples:

```
puppeteer.content:SESSION_ID
```

## [puppeteer.title]

Returns page title.

Arguments:

* Slot value - Session identifier.

Examples:

```
puppeteer.title:SESSION_ID
```

## [puppeteer.url]

Returns current URL.

Arguments:

* Slot value - Session identifier.

Examples:

```
puppeteer.url:SESSION_ID
```

## [puppeteer.screenshot]

Saves a screenshot to disk.

Arguments:

* Slot value - Session identifier.
* `filename` - Output file path.
* `full-page` - Boolean. Capture full scrollable page.
* `type` - `png` or `jpeg`.
* `quality` - JPEG quality 0-100 (only for `jpeg`).

Examples:

```
puppeteer.screenshot:SESSION_ID
   filename:"/etc/tmp/example.png"
   full-page:true
```

```
puppeteer.screenshot:SESSION_ID
   filename:"/etc/tmp/example.jpg"
   type:jpeg
   quality:85
```

## [puppeteer.evaluate]

Evaluates a JavaScript expression in the page.

Arguments:

* Slot value - Session identifier.
* `expression` - JavaScript expression string.
* `args` - Optional arguments for JS function invocation. Each child value is one argument.

Examples:

```
puppeteer.evaluate:SESSION_ID
   expression:"document.title"
```

```
puppeteer.evaluate:SESSION_ID
   expression:"typeof window.mcaptcha"
```

## Combination examples

Get title and URL from a page, then close the session.

```
.session_id
set-value:x:@.session_id
   puppeteer.connect

puppeteer.goto:x:@.session_id
   url:"https://ainiro.io"

puppeteer.title:x:@.session_id
puppeteer.url:x:@.session_id

puppeteer.close:x:@.session_id
```

Fetch page HTML and save a screenshot.

```
.session_id
set-value:x:@.session_id
   puppeteer.connect

puppeteer.goto:x:@.session_id
   url:"https://ainiro.io/contact-us"

puppeteer.content:x:@.session_id
puppeteer.screenshot:x:@.session_id
   filename:"/etc/tmp/ainiro-contact.png"
   full-page:true

puppeteer.close:x:@.session_id
```
