snapshot of https://github.com/tauri-apps/tauri.git (dev, 2026-09-23; blobs > 131072B omitted)

packages/api-e2e/test/helpers/index.ts

@@ -0,0 +1,243 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { browser } from '@wdio/globals'
+import type * as TauriApi from '@tauri-apps/api'
+
+/** The full `@tauri-apps/api` surface, as exposed on `window.__TAURI__`. */
+export type Api = typeof TauriApi
+
+/** OS the app under test runs on. */
+export type Platform = NodeJS.Platform | 'android' | 'ios'
+
+/**
+ * The platform of the app under test. The desktop suite drives an app on the
+ * host, so it is `process.platform`; the mobile configs (`wdio.android.conf.ts`,
+ * `wdio.ios.conf.ts`) drive an emulator/simulator and set `E2E_PLATFORM` for
+ * the spec workers instead.
+ */
+export const platform: Platform =
+  (process.env.E2E_PLATFORM as Platform | undefined) ?? process.platform
+
+export const isMobile = platform === 'android' || platform === 'ios'
+
+type PageOutcome<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: string; stack?: string }
+
+/** Thrown when the function passed to {@link tauri} rejects inside the webview. */
+export class TauriPageError extends Error {
+  pageStack?: string
+  constructor(message: string, pageStack?: string) {
+    super(message)
+    this.name = 'TauriPageError'
+    this.pageStack = pageStack
+  }
+}
+
+/**
+ * Runs `fn` inside the app's webview with `window.__TAURI__` as its first argument
+ * and resolves with its (JSON-serializable) return value.
+ *
+ * `fn` is serialized with `Function.prototype.toString`, so it **cannot close over
+ * anything in the spec module** — every value it needs must be passed through `args`,
+ * and it may only reference `api`, those args, and browser globals (`window`,
+ * `document`, `setTimeout`, `Promise`, ...).
+ *
+ * @example
+ * const name = await tauri((api) => api.app.getName())
+ * const sum = await tauri((api, a, b) => a + b, 2, 3)
+ */
+export async function tauri<R, A extends unknown[]>(
+  fn: (api: Api, ...args: A) => R,
+  ...args: A
+): Promise<Awaited<R>> {
+  // A string body (rather than passing `fn` directly) keeps this working across
+  // both the classic and bidi WebDriver protocols and avoids any in-page eval of
+  // our own — the driver injects this script itself, which is exempt from the
+  // app's CSP. `executeAsync` is used because promise support in `execute` is not
+  // uniform across the platform drivers tauri-driver proxies to.
+  //
+  // The outcome crosses the driver as a JSON string rather than an object so no
+  // driver gets to interpret its shape: the Selenium atoms that Appium runs
+  // scripts through on iOS turn any object with a numeric `length` property
+  // into an array.
+  const script = `
+    var done = arguments[arguments.length - 1];
+    var args = Array.prototype.slice.call(arguments, 0, arguments.length - 1);
+    var fn = (${fn.toString()});
+    Promise.resolve()
+      .then(function () { return fn.apply(null, [window.__TAURI__].concat(args)); })
+      .then(
+        function (value) { return { ok: true, value: value === undefined ? null : value }; },
+        function (error) {
+          return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined
+          };
+        }
+      )
+      .then(function (outcome) {
+        try {
+          done(JSON.stringify(outcome));
+        } catch (error) {
+          done(JSON.stringify({ ok: false, error: 'result is not JSON-serializable: ' + error }));
+        }
+      });
+  `
+  const raw = await browser.executeAsync(script, ...args)
+  const outcome = (
+    typeof raw === 'string' ? JSON.parse(raw) : raw
+  ) as PageOutcome<Awaited<R>> | null
+  if (!outcome || typeof outcome !== 'object' || !('ok' in outcome)) {
+    throw new Error(
+      `tauri() bridge returned an unexpected value: ${JSON.stringify(outcome)}`
+    )
+  }
+  if (!outcome.ok) {
+    throw new TauriPageError(outcome.error, outcome.stack)
+  }
+  return outcome.value
+}
+
+/**
+ * Asserts that the page-side call rejects and returns the rejection message,
+ * so specs can assert on it. Throws if the call unexpectedly resolves.
+ */
+export async function tauriError<A extends unknown[]>(
+  fn: (api: Api, ...args: A) => unknown,
+  ...args: A
+): Promise<string> {
+  try {
+    await tauri(fn, ...args)
+  } catch (error) {
+    if (error instanceof TauriPageError) {
+      return error.message
+    }
+    // Some platform drivers (notably the Linux WebKitWebDriver) surface a
+    // page-side `invoke` rejection as a WebDriver-level error on the
+    // `execute/async` command instead of letting the in-page bridge report it
+    // as an `{ ok: false }` outcome. Fall back to that error's message so the
+    // backend rejection is still assertable. This is safe for error-path specs:
+    // they match the message against an expected pattern, so a genuine driver
+    // failure (whose message won't match) still fails the test.
+    if (error instanceof Error) {
+      return error.message
+    }
+    throw error
+  }
+  throw new Error('expected the API call to reject, but it resolved')
+}
+
+/**
+ * Polls `check` until it returns without throwing or `timeout` elapses.
+ * Use for state that a window manager applies asynchronously (focus, minimize, ...).
+ */
+export async function eventually<T>(
+  check: () => T | Promise<T>,
+  {
+    timeout = 10_000,
+    interval = 250
+  }: { timeout?: number; interval?: number } = {}
+): Promise<T> {
+  const deadline = Date.now() + timeout
+  let lastError: unknown
+  for (;;) {
+    try {
+      return await check()
+    } catch (error) {
+      lastError = error
+    }
+    if (Date.now() > deadline) {
+      throw lastError instanceof Error
+        ? lastError
+        : new Error(String(lastError))
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval))
+  }
+}
+
+const skippedModules = (process.env.E2E_SKIP ?? '')
+  .split(',')
+  .map((entry) => entry.trim())
+  .filter(Boolean)
+
+export interface DescribeApiOptions {
+  /**
+   * The module's plugin is not registered at all on mobile (`menu`, `tray`),
+   * so the whole suite is skipped there.
+   */
+  desktopOnly?: boolean
+}
+
+/**
+ * `describe` wrapper keyed by API module name. Any module listed in the
+ * comma-separated `E2E_SKIP` env var (e.g. `E2E_SKIP=tray,menu`) is skipped.
+ */
+export function describeApi(module: string, fn: () => void): void
+export function describeApi(
+  module: string,
+  options: DescribeApiOptions,
+  fn: () => void
+): void
+export function describeApi(
+  module: string,
+  optionsOrFn: DescribeApiOptions | (() => void),
+  maybeFn?: () => void
+): void {
+  const [options, fn] =
+    typeof optionsOrFn === 'function'
+      ? [{} as DescribeApiOptions, optionsOrFn]
+      : [optionsOrFn, maybeFn!]
+  const title = `@tauri-apps/api/${module}`
+  if (skippedModules.includes(module) || (options.desktopOnly && isMobile)) {
+    describe.skip(title, fn)
+  } else {
+    describe(title, fn)
+  }
+}
+
+/**
+ * `it` restricted to the given platform(s); skipped (as pending) elsewhere.
+ * Use for behavior that only exists on one OS, e.g. `activityName()` on Android.
+ */
+export function itOn(
+  platforms: Platform | Platform[],
+  title: string,
+  fn: () => void | Promise<void>
+): void {
+  const list = Array.isArray(platforms) ? platforms : [platforms]
+  if (list.includes(platform)) {
+    it(title, fn)
+  } else {
+    it.skip(title, fn)
+  }
+}
+
+/**
+ * `it` for desktop-only APIs. The mobile builds do not register the commands
+ * behind them (`#[cfg(desktop)]` in the core plugins) or implement them as
+ * no-ops (window title, size, resizability), so they are skipped on mobile.
+ */
+export function itDesktop(title: string, fn: () => void | Promise<void>): void {
+  if (isMobile) {
+    it.skip(title, fn)
+  } else {
+    it(title, fn)
+  }
+}
+
+/**
+ * `it` for assertions that depend on a real window manager (minimize, maximize,
+ * focus, ...). Skipped entirely when `E2E_SKIP_WM` is set (e.g. bare headless CI),
+ * and on mobile, which has no window manager (nor those commands).
+ */
+export function itWm(title: string, fn: () => void | Promise<void>): void {
+  if (process.env.E2E_SKIP_WM || isMobile) {
+    it.skip(title, fn)
+  } else {
+    it(title, fn)
+  }
+}

packages/api-e2e/test/specs/app.spec.ts

@@ -0,0 +1,64 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import {
+  tauri,
+  eventually,
+  describeApi,
+  platform,
+  isMobile
+} from '../helpers/index.js'
+
+describeApi('app', () => {
+  it('getName returns the configured product name', async () => {
+    expect(await tauri((api) => api.app.getName())).toBe('Tauri API')
+  })
+
+  it('getVersion returns the configured version', async () => {
+    expect(await tauri((api) => api.app.getVersion())).toBe('1.0.0')
+  })
+
+  it('getTauriVersion returns a semver string', async () => {
+    expect(await tauri((api) => api.app.getTauriVersion())).toMatch(
+      /^\d+\.\d+\.\d+/
+    )
+  })
+
+  it('getIdentifier returns the bundle identifier', async () => {
+    expect(await tauri((api) => api.app.getIdentifier())).toBe('com.tauri.api')
+  })
+
+  it('defaultWindowIcon returns an image with a positive size', async () => {
+    const size = await tauri(async (api) => {
+      const icon = await api.app.defaultWindowIcon()
+      return icon ? await icon.size() : null
+    })
+    expect(size).not.toBeNull()
+    expect(size!.width).toBeGreaterThan(0)
+    expect(size!.height).toBeGreaterThan(0)
+  })
+
+  it('setTheme applies a theme and can be reset to the system default', async () => {
+    await tauri((api) => api.app.setTheme('dark'))
+    // On Linux the app-level theme is not observable through `window.theme()`:
+    // tao's event-loop `set_theme` only flips the GTK `prefer-dark` setting and
+    // never updates the window's stored theme, so `theme()` keeps reporting the
+    // portal/system value (and blocks on a 5s dbus timeout when no portal runs,
+    // as in headless CI). On mobile `set_theme` is a no-op and `theme()` always
+    // reports `light`. Elsewhere the change is reflected on the window.
+    if (platform !== 'linux' && !isMobile) {
+      await eventually(async () => {
+        const theme = await tauri((api) =>
+          api.window.getCurrentWindow().theme()
+        )
+        if (theme !== 'dark') {
+          throw new Error(`expected theme "dark", got "${theme}"`)
+        }
+      })
+    }
+    // restore
+    await tauri((api) => api.app.setTheme(null))
+  })
+})

packages/api-e2e/test/specs/core.spec.ts

@@ -0,0 +1,109 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import { tauri, tauriError, describeApi, itOn } from '../helpers/index.js'
+
+describeApi('core', () => {
+  it('isTauri reports true inside the app', async () => {
+    expect(await tauri((api) => api.core.isTauri())).toBe(true)
+  })
+
+  it('invoke round-trips a raw request through the echo command', async () => {
+    const echoed = await tauri((api) =>
+      api.core.invoke('echo', { some: 'payload', n: 42 })
+    )
+    expect(echoed).toEqual({ some: 'payload', n: 42 })
+  })
+
+  it('invoke rejects for a command that is not registered', async () => {
+    // `removeUnusedCommands` strips ungranted commands from the app entirely.
+    const message = await tauriError((api) =>
+      api.core.invoke('this_command_does_not_exist')
+    )
+    expect(message).toMatch(/not found|not allowed|denied/i)
+  })
+
+  it('command scopes gate log_operation by event', async () => {
+    // The run-app capability scopes `log_operation` to the `tauri-click` event.
+    await tauri((api) =>
+      api.core.invoke('log_operation', {
+        event: 'tauri-click',
+        payload: 'from e2e'
+      })
+    )
+    const message = await tauriError((api) =>
+      api.core.invoke('log_operation', { event: 'out-of-scope-event' })
+    )
+    expect(message).toMatch(/not allowed|denied/i)
+  })
+
+  it('Channel receives every message streamed from the backend in order', async () => {
+    // `spam` sends 1..=1000 over the channel.
+    const result = await tauri(
+      (api, count) =>
+        new Promise<{ length: number; ordered: boolean; last: number }>(
+          (resolve, reject) => {
+            const received: number[] = []
+            const channel = new api.core.Channel<number>()
+            channel.onmessage = (value: number) => {
+              received.push(value)
+              if (received.length === count) {
+                let ordered = true
+                for (let i = 0; i < received.length; i++) {
+                  if (received[i] !== i + 1) {
+                    ordered = false
+                    break
+                  }
+                }
+                resolve({
+                  length: received.length,
+                  ordered,
+                  last: received[received.length - 1]
+                })
+              }
+            }
+            api.core.invoke('spam', { channel }).catch(reject)
+            setTimeout(
+              () =>
+                reject(
+                  new Error(
+                    `only received ${received.length} of ${count} messages`
+                  )
+                ),
+              15000
+            )
+          }
+        ),
+      1000
+    )
+    expect(result.length).toBe(1000)
+    expect(result.ordered).toBe(true)
+    expect(result.last).toBe(1000)
+  })
+
+  itOn(
+    ['android', 'ios'],
+    'a mobile plugin resolves JSArray and JSObject values as JSON arrays and objects',
+    async () => {
+      // On Android, the sample plugin's `jsValues` goes through
+      // `Invoke.resolveObject`, i.e. the plugin JSON mapper rather than
+      // org.json's own `toString`.
+      const values = await tauri((api) =>
+        api.core.invoke('plugin:sample|js_values')
+      )
+      expect(values).toEqual({
+        array: ['a', 1, true],
+        obj: { kind: 'object', nested: [1, 2] }
+      })
+    }
+  )
+
+  it('convertFileSrc builds a platform-appropriate asset URL', async () => {
+    const url = await tauri((api) =>
+      api.core.convertFileSrc('/path/to/file.png')
+    )
+    expect(url).toMatch(/(asset:\/\/localhost\/|https?:\/\/asset\.localhost\/)/)
+  })
+})

packages/api-e2e/test/specs/dpi.spec.ts

@@ -0,0 +1,54 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import { tauri, describeApi } from '../helpers/index.js'
+
+describeApi('dpi', () => {
+  it('LogicalSize.toPhysical scales up by the factor', async () => {
+    const physical = await tauri((api) => {
+      const size = new api.dpi.LogicalSize(100, 50).toPhysical(2)
+      return { width: size.width, height: size.height }
+    })
+    expect(physical).toEqual({ width: 200, height: 100 })
+  })
+
+  it('PhysicalSize.toLogical scales down by the factor', async () => {
+    const logical = await tauri((api) => {
+      const size = new api.dpi.PhysicalSize(200, 100).toLogical(2)
+      return { width: size.width, height: size.height }
+    })
+    expect(logical).toEqual({ width: 100, height: 50 })
+  })
+
+  it('LogicalPosition.toPhysical and PhysicalPosition.toLogical round-trip', async () => {
+    const result = await tauri((api) => {
+      const physical = new api.dpi.LogicalPosition(10, 20).toPhysical(2)
+      const logical = new api.dpi.PhysicalPosition(10, 20).toLogical(2)
+      return {
+        physical: { x: physical.x, y: physical.y },
+        logical: { x: logical.x, y: logical.y }
+      }
+    })
+    expect(result.physical).toEqual({ x: 20, y: 40 })
+    expect(result.logical).toEqual({ x: 5, y: 10 })
+  })
+
+  it('Size and Position wrappers delegate conversions', async () => {
+    const result = await tauri((api) => {
+      const size = new api.dpi.Size(
+        new api.dpi.LogicalSize(100, 50)
+      ).toPhysical(2)
+      const position = new api.dpi.Position(
+        new api.dpi.PhysicalPosition(20, 40)
+      ).toLogical(2)
+      return {
+        size: { width: size.width, height: size.height },
+        position: { x: position.x, y: position.y }
+      }
+    })
+    expect(result.size).toEqual({ width: 200, height: 100 })
+    expect(result.position).toEqual({ x: 10, y: 20 })
+  })
+})

packages/api-e2e/test/specs/event.spec.ts

@@ -0,0 +1,125 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import { tauri, describeApi } from '../helpers/index.js'
+
+describeApi('event', () => {
+  it('listen receives an emitted payload', async () => {
+    const payload = await tauri(
+      (api) =>
+        new Promise<{ hello: string }>((resolve, reject) => {
+          api.event
+            .listen<{ hello: string }>('e2e://ping', (event) =>
+              resolve(event.payload)
+            )
+            .then((unlisten) => {
+              api.event.emit('e2e://ping', { hello: 'world' }).catch(reject)
+              setTimeout(() => {
+                unlisten()
+                reject(new Error('event was not received'))
+              }, 5000)
+            })
+            .catch(reject)
+        })
+    )
+    expect(payload).toEqual({ hello: 'world' })
+  })
+
+  it('once fires exactly once even if the event is emitted twice', async () => {
+    const count = await tauri(
+      (api) =>
+        new Promise<number>((resolve, reject) => {
+          let calls = 0
+          api.event
+            .once('e2e://once', () => {
+              calls++
+            })
+            .then(async () => {
+              await api.event.emit('e2e://once')
+              await api.event.emit('e2e://once')
+              setTimeout(() => resolve(calls), 1000)
+            })
+            .catch(reject)
+        })
+    )
+    expect(count).toBe(1)
+  })
+
+  it('unlisten stops further delivery', async () => {
+    const count = await tauri(
+      (api) =>
+        new Promise<number>((resolve, reject) => {
+          let calls = 0
+          api.event
+            .listen('e2e://off', () => {
+              calls++
+            })
+            .then(async (unlisten) => {
+              await api.event.emit('e2e://off')
+              setTimeout(async () => {
+                await unlisten()
+                await api.event.emit('e2e://off')
+                setTimeout(() => resolve(calls), 500)
+              }, 500)
+            })
+            .catch(reject)
+        })
+    )
+    expect(count).toBe(1)
+  })
+
+  it('emitTo delivers only to the targeted label', async () => {
+    const result = await tauri(
+      (api) =>
+        new Promise<{ mainCount: number }>((resolve, reject) => {
+          let mainCount = 0
+          api.event
+            // The listener must be scoped to the `main` label: a default
+            // `listen()` registers the `Any` target, a catch-all that receives
+            // every emit regardless of the `emitTo` label (so it would also see
+            // the `does-not-exist` emit).
+            .listen(
+              'e2e://target',
+              () => {
+                mainCount++
+              },
+              { target: 'main' }
+            )
+            .then(async (unlisten) => {
+              await api.event.emitTo('main', 'e2e://target') // delivered
+              await api.event.emitTo('does-not-exist', 'e2e://target') // dropped
+              setTimeout(async () => {
+                await unlisten()
+                resolve({ mainCount })
+              }, 800)
+            })
+            .catch(reject)
+        })
+    )
+    expect(result.mainCount).toBe(1)
+  })
+
+  it('bridges events to and from the Rust backend', async () => {
+    // examples/api listens for `js-event` and replies with `rust-event { data }`.
+    const reply = await tauri(
+      (api) =>
+        new Promise<{ data: string }>((resolve, reject) => {
+          api.event
+            .listen<{ data: string }>('rust-event', (event) =>
+              resolve(event.payload)
+            )
+            .then((unlisten) => {
+              api.event.emit('js-event', 'hello from e2e').catch(reject)
+              setTimeout(() => {
+                unlisten()
+                reject(new Error('no rust-event reply received'))
+              }, 5000)
+            })
+            .catch(reject)
+        })
+    )
+    expect(reply).toEqual({ data: 'something else' })
+  })
+})

packages/api-e2e/test/specs/image.spec.ts

@@ -0,0 +1,31 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import { tauri, describeApi } from '../helpers/index.js'
+
+describeApi('image', () => {
+  it('Image.new round-trips raw rgba pixels', async () => {
+    // 2x1 image: red pixel, green pixel.
+    const rgba = [255, 0, 0, 255, 0, 255, 0, 255]
+    const result = await tauri(
+      async (api, pixels, width, height) => {
+        const image = await api.image.Image.new(pixels, width, height)
+        const size = await image.size()
+        const bytes = await image.rgba()
+        return {
+          width: size.width,
+          height: size.height,
+          byteLength: bytes.length
+        }
+      },
+      rgba,
+      2,
+      1
+    )
+    expect(result.width).toBe(2)
+    expect(result.height).toBe(1)
+    expect(result.byteLength).toBe(rgba.length)
+  })
+})

packages/api-e2e/test/specs/menu.spec.ts

@@ -0,0 +1,88 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import { tauri, describeApi } from '../helpers/index.js'
+
+// The menu commands are all allowed by default. These tests only build and
+// inspect menu resources; they deliberately do not attach the menu to the app
+// or window, to avoid disturbing the live example app. The menu plugin is
+// desktop-only, so the whole module is skipped on mobile.
+describeApi('menu', { desktopOnly: true }, () => {
+  it('Menu.new builds a menu with the given items', async () => {
+    const result = await tauri(async (api) => {
+      const item = await api.menu.MenuItem.new({ text: 'Item A' })
+      const check = await api.menu.CheckMenuItem.new({
+        text: 'Item B',
+        checked: true
+      })
+      const separator = await api.menu.PredefinedMenuItem.new({
+        item: 'Separator'
+      })
+      const submenu = await api.menu.Submenu.new({
+        text: 'More',
+        items: [await api.menu.MenuItem.new({ text: 'Nested' })]
+      })
+      const menu = await api.menu.Menu.new({
+        items: [item, check, separator, submenu]
+      })
+      const items = await menu.items()
+      return { count: items.length }
+    })
+    expect(result.count).toBe(4)
+  })
+
+  it('MenuItem text and enabled state can be read and updated', async () => {
+    const result = await tauri(async (api) => {
+      const item = await api.menu.MenuItem.new({
+        text: 'Original',
+        enabled: true
+      })
+      const before = await item.text()
+      await item.setText('Updated')
+      const after = await item.text()
+      const enabledBefore = await item.isEnabled()
+      await item.setEnabled(false)
+      const enabledAfter = await item.isEnabled()
+      return { before, after, enabledBefore, enabledAfter }
+    })
+    expect(result.before).toBe('Original')
+    expect(result.after).toBe('Updated')
+    expect(result.enabledBefore).toBe(true)
+    expect(result.enabledAfter).toBe(false)
+  })
+
+  it('CheckMenuItem tracks its checked state', async () => {
+    const result = await tauri(async (api) => {
+      const item = await api.menu.CheckMenuItem.new({
+        text: 'Toggle',
+        checked: false
+      })
+      // On Windows the checked state lives in the native menu the item belongs
+      // to, so it must be attached to a menu to be readable.
+      await api.menu.Menu.new({ items: [item] })
+      const before = await item.isChecked()
+      await item.setChecked(true)
+      const after = await item.isChecked()
+      return { before, after }
+    })
+    expect(result.before).toBe(false)
+    expect(result.after).toBe(true)
+  })
+
+  it('append and removeAt mutate the item list', async () => {
+    const result = await tauri(async (api) => {
+      const menu = await api.menu.Menu.new({
+        items: [await api.menu.MenuItem.new({ text: 'First' })]
+      })
+      await menu.append(await api.menu.MenuItem.new({ text: 'Second' }))
+      const afterAppend = (await menu.items()).length
+      await menu.removeAt(0)
+      const afterRemove = (await menu.items()).length
+      return { afterAppend, afterRemove }
+    })
+    expect(result.afterAppend).toBe(2)
+    expect(result.afterRemove).toBe(1)
+  })
+})

packages/api-e2e/test/specs/path.spec.ts

@@ -0,0 +1,62 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import nodePath from 'node:path'
+import { expect } from '@wdio/globals'
+import { tauri, describeApi, platform } from '../helpers/index.js'
+
+// Node's path module for the platform the *app* runs on. That is the host for
+// the desktop suite, but the mobile suites drive an Android/iOS app (POSIX
+// paths) from whatever OS hosts the emulator/simulator.
+const path = platform === 'win32' ? nodePath.win32 : nodePath.posix
+
+describeApi('path', () => {
+  it('sep and delimiter match the target platform', async () => {
+    const separators = await tauri((api) => ({
+      sep: api.path.sep(),
+      delimiter: api.path.delimiter()
+    }))
+    expect(separators.sep).toBe(path.sep)
+    expect(separators.delimiter).toBe(path.delimiter)
+  })
+
+  it('join, dirname, basename and extname behave like the platform', async () => {
+    const result = await tauri(async (api) => ({
+      joined: await api.path.join('a', 'b', 'c.txt'),
+      dir: await api.path.dirname(await api.path.join('a', 'b', 'c.txt')),
+      base: await api.path.basename(await api.path.join('a', 'b', 'c.txt')),
+      ext: await api.path.extname(await api.path.join('a', 'b', 'c.txt'))
+    }))
+    expect(result.joined).toBe(path.join('a', 'b', 'c.txt'))
+    expect(result.base).toBe('c.txt')
+    expect(result.ext).toBe('txt')
+    expect(result.dir.endsWith(path.join('a', 'b'))).toBe(true)
+  })
+
+  it('normalize and isAbsolute work', async () => {
+    const result = await tauri(async (api) => ({
+      normalized: await api.path.normalize('a/b/../c'),
+      absoluteIsAbsolute: await api.path.isAbsolute(
+        await api.path.resolve('x')
+      ),
+      relativeIsAbsolute: await api.path.isAbsolute('a/b')
+    }))
+    expect(result.normalized).toContain('c')
+    expect(result.absoluteIsAbsolute).toBe(true)
+    expect(result.relativeIsAbsolute).toBe(false)
+  })
+
+  it('app directories are absolute and scoped to the identifier', async () => {
+    const dirs = await tauri(async (api) => ({
+      appData: await api.path.appDataDir(),
+      appConfig: await api.path.appConfigDir(),
+      home: await api.path.homeDir(),
+      temp: await api.path.tempDir()
+    }))
+    expect(dirs.appData).toContain('com.tauri.api')
+    expect(dirs.appConfig.length).toBeGreaterThan(0)
+    expect(dirs.home.length).toBeGreaterThan(0)
+    expect(dirs.temp.length).toBeGreaterThan(0)
+  })
+})

packages/api-e2e/test/specs/tray.spec.ts

@@ -0,0 +1,43 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import { tauri, describeApi } from '../helpers/index.js'
+
+// Tray commands are allowed by default, but a tray host is not always available
+// in headless environments — set `E2E_SKIP=tray` there. The tray plugin is
+// desktop-only, so the whole module is skipped on mobile.
+describeApi('tray', { desktopOnly: true }, () => {
+  it('creates a tray icon, looks it up and removes it', async () => {
+    const created = await tauri(async (api) => {
+      const icon = await api.app.defaultWindowIcon()
+      const tray = await api.tray.TrayIcon.new({
+        id: 'e2e-tray',
+        icon: icon ?? undefined,
+        tooltip: 'e2e tray'
+      })
+      return tray.id
+    })
+    expect(created).toBe('e2e-tray')
+
+    const foundById = await tauri(async (api) => {
+      const tray = await api.tray.TrayIcon.getById('e2e-tray')
+      return tray !== null
+    })
+    expect(foundById).toBe(true)
+
+    await tauri(async (api) => {
+      const tray = await api.tray.TrayIcon.getById('e2e-tray')
+      await tray?.setVisible(true)
+      return null
+    })
+
+    const removed = await tauri(async (api) => {
+      await api.tray.TrayIcon.removeById('e2e-tray')
+      const tray = await api.tray.TrayIcon.getById('e2e-tray')
+      return tray === null
+    })
+    expect(removed).toBe(true)
+  })
+})

packages/api-e2e/test/specs/webview.spec.ts

@@ -0,0 +1,44 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import { tauri, describeApi, itDesktop } from '../helpers/index.js'
+
+describeApi('webview', () => {
+  it('getCurrentWebview reports the main label', async () => {
+    expect(await tauri((api) => api.webview.getCurrentWebview().label)).toBe(
+      'main'
+    )
+  })
+
+  it('getAllWebviews includes the main webview', async () => {
+    const labels = await tauri(async (api) =>
+      (await api.webview.getAllWebviews()).map((w) => w.label)
+    )
+    expect(labels).toContain('main')
+  })
+
+  // `webview_position`/`webview_size` are desktop-only commands: on mobile the
+  // webview always fills the window.
+  itDesktop('exposes a physical position and size', async () => {
+    const rect = await tauri(async (api) => {
+      const wv = api.webview.getCurrentWebview()
+      const pos = await wv.position()
+      const size = await wv.size()
+      return { x: pos.x, y: pos.y, width: size.width, height: size.height }
+    })
+    expect(rect.width).toBeGreaterThan(0)
+    expect(rect.height).toBeGreaterThan(0)
+  })
+
+  itDesktop('setZoom adjusts and restores the zoom level', async () => {
+    // Requires `core:webview:allow-set-webview-zoom` in the run-app capability.
+    await tauri(async (api) => {
+      const wv = api.webview.getCurrentWebview()
+      await wv.setZoom(1.5)
+      await wv.setZoom(1)
+      return null
+    })
+  })
+})

packages/api-e2e/test/specs/webviewWindow.spec.ts

@@ -0,0 +1,64 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import { tauri, eventually, describeApi, itDesktop } from '../helpers/index.js'
+
+describeApi('webviewWindow', () => {
+  it('getCurrentWebviewWindow reports the main label', async () => {
+    expect(
+      await tauri((api) => api.webviewWindow.getCurrentWebviewWindow().label)
+    ).toBe('main')
+  })
+
+  // On mobile a new window is a new Android activity / iOS scene that takes
+  // over the foreground (and the automation session's webview context), so
+  // this is only exercised on desktop.
+  itDesktop('creates, finds and closes a new webview window', async () => {
+    // The label must match `main-*` to inherit the run-app capability.
+    const created = await tauri(
+      (api) =>
+        new Promise<boolean>((resolve, reject) => {
+          const w = new api.webviewWindow.WebviewWindow('main-e2e', {
+            width: 400,
+            height: 300
+          })
+          w.once('tauri://created', () => resolve(true)).catch(reject)
+          w.once('tauri://error', (event) =>
+            reject(
+              new Error(`window creation failed: ${String(event.payload)}`)
+            )
+          ).catch(reject)
+          setTimeout(() => reject(new Error('window creation timed out')), 8000)
+        })
+    )
+    expect(created).toBe(true)
+
+    const found = await tauri(async (api) => {
+      const byLabel =
+        await api.webviewWindow.WebviewWindow.getByLabel('main-e2e')
+      const all = (await api.webviewWindow.getAllWebviewWindows()).map(
+        (w) => w.label
+      )
+      return { exists: byLabel !== null, all }
+    })
+    expect(found.exists).toBe(true)
+    expect(found.all).toContain('main-e2e')
+
+    await tauri(async (api) => {
+      const w = await api.webviewWindow.WebviewWindow.getByLabel('main-e2e')
+      await w?.close()
+      return null
+    })
+
+    await eventually(async () => {
+      const labels = await tauri(async (api) =>
+        (await api.webviewWindow.getAllWebviewWindows()).map((w) => w.label)
+      )
+      if (labels.includes('main-e2e')) {
+        throw new Error('window is still present after close')
+      }
+    })
+  })
+})

packages/api-e2e/test/specs/window.spec.ts

@@ -0,0 +1,295 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+import { expect } from '@wdio/globals'
+import {
+  tauri,
+  eventually,
+  describeApi,
+  itWm,
+  itDesktop,
+  itOn
+} from '../helpers/index.js'
+
+describeApi('window', () => {
+  it('getCurrentWindow reports the main label', async () => {
+    expect(await tauri((api) => api.window.getCurrentWindow().label)).toBe(
+      'main'
+    )
+  })
+
+  it('getAllWindows includes the main window', async () => {
+    const labels = await tauri(async (api) =>
+      (await api.window.getAllWindows()).map((w) => w.label)
+    )
+    expect(labels).toContain('main')
+  })
+
+  // Mobile windows have no title bar: `title()` is always empty and
+  // `setTitle` a no-op there.
+  itDesktop('title can be read and set', async () => {
+    const original = await tauri((api) => api.window.getCurrentWindow().title())
+    await tauri((api) => api.window.getCurrentWindow().setTitle('e2e title'))
+    expect(await tauri((api) => api.window.getCurrentWindow().title())).toBe(
+      'e2e title'
+    )
+    // restore
+    await tauri(
+      (api, title) => api.window.getCurrentWindow().setTitle(title),
+      original
+    )
+  })
+
+  it('reports a positive scale factor and sizes', async () => {
+    const metrics = await tauri(async (api) => {
+      const w = api.window.getCurrentWindow()
+      const scale = await w.scaleFactor()
+      const inner = await w.innerSize()
+      const outer = await w.outerSize()
+      return {
+        scale,
+        inner: { width: inner.width, height: inner.height },
+        outer: { width: outer.width, height: outer.height }
+      }
+    })
+    expect(metrics.scale).toBeGreaterThan(0)
+    expect(metrics.inner.width).toBeGreaterThan(0)
+    expect(metrics.inner.height).toBeGreaterThan(0)
+    expect(metrics.outer.width).toBeGreaterThanOrEqual(metrics.inner.width)
+  })
+
+  itOn(
+    'android',
+    'activityName reports the activity hosting the window',
+    async () => {
+      const name = await tauri((api) =>
+        api.window.getCurrentWindow().activityName()
+      )
+      expect(name).toMatch(/MainActivity/)
+    }
+  )
+
+  // The window is the whole screen on mobile: `set_size` is a no-op.
+  itDesktop('setSize resizes the window', async () => {
+    const scale = await tauri((api) =>
+      api.window.getCurrentWindow().scaleFactor()
+    )
+    const original = await tauri(async (api) => {
+      const size = await api.window.getCurrentWindow().innerSize()
+      return { width: size.width, height: size.height }
+    })
+
+    await tauri(
+      (api, width, height) =>
+        api.window
+          .getCurrentWindow()
+          .setSize(new api.dpi.LogicalSize(width, height)),
+      600,
+      400
+    )
+
+    await eventually(async () => {
+      const inner = await tauri(async (api) => {
+        const size = await api.window.getCurrentWindow().innerSize()
+        return { width: size.width, height: size.height }
+      })
+      const tolerance = Math.ceil(scale) * 4
+      if (Math.abs(inner.width - 600 * scale) > tolerance) {
+        throw new Error(`width ${inner.width} not near ${600 * scale}`)
+      }
+      if (Math.abs(inner.height - 400 * scale) > tolerance) {
+        throw new Error(`height ${inner.height} not near ${400 * scale}`)
+      }
+    })
+
+    // restore the original physical size
+    await tauri(
+      (api, width, height) =>
+        api.window
+          .getCurrentWindow()
+          .setSize(new api.dpi.PhysicalSize(width, height)),
+      original.width,
+      original.height
+    )
+  })
+
+  // Mobile windows are never resizable (`is_resizable` is always `false`).
+  itDesktop('setResizable toggles resizability', async () => {
+    await tauri((api) => api.window.getCurrentWindow().setResizable(false))
+    expect(
+      await tauri((api) => api.window.getCurrentWindow().isResizable())
+    ).toBe(false)
+    await tauri((api) => api.window.getCurrentWindow().setResizable(true))
+    expect(
+      await tauri((api) => api.window.getCurrentWindow().isResizable())
+    ).toBe(true)
+  })
+
+  // Desktop-only commands (`#[cfg(desktop)]` in the window plugin).
+  itDesktop('assorted setters resolve without throwing', async () => {
+    await tauri(async (api) => {
+      const w = api.window.getCurrentWindow()
+      await w.setAlwaysOnTop(true)
+      await w.setAlwaysOnTop(false)
+      await w.setShadow(true)
+      await w.setContentProtected(false)
+      await w.setCursorVisible(true)
+      await w.requestUserAttention(null)
+      return null
+    })
+  })
+
+  itWm('setPosition moves the window', async () => {
+    const original = await tauri(async (api) => {
+      const pos = await api.window.getCurrentWindow().outerPosition()
+      return { x: pos.x, y: pos.y }
+    })
+
+    await tauri(
+      (api, x, y) =>
+        api.window
+          .getCurrentWindow()
+          .setPosition(new api.dpi.PhysicalPosition(x, y)),
+      original.x + 40,
+      original.y + 40
+    )
+
+    await eventually(async () => {
+      const pos = await tauri(async (api) => {
+        const p = await api.window.getCurrentWindow().outerPosition()
+        return { x: p.x, y: p.y }
+      })
+      // Window managers can nudge the final position; allow a generous tolerance.
+      if (
+        Math.abs(pos.x - (original.x + 40)) > 30
+        || Math.abs(pos.y - (original.y + 40)) > 30
+      ) {
+        throw new Error(
+          `position ${pos.x},${pos.y} not near ${original.x + 40},${original.y + 40}`
+        )
+      }
+    })
+
+    await tauri(
+      (api, x, y) =>
+        api.window
+          .getCurrentWindow()
+          .setPosition(new api.dpi.PhysicalPosition(x, y)),
+      original.x,
+      original.y
+    )
+  })
+
+  itWm('minimize and unminimize toggle the minimized state', async () => {
+    await tauri((api) => api.window.getCurrentWindow().minimize())
+    await eventually(async () => {
+      if (
+        !(await tauri((api) => api.window.getCurrentWindow().isMinimized()))
+      ) {
+        throw new Error('window is not minimized')
+      }
+    })
+    await tauri((api) => api.window.getCurrentWindow().unminimize())
+    await eventually(async () => {
+      if (await tauri((api) => api.window.getCurrentWindow().isMinimized())) {
+        throw new Error('window is still minimized')
+      }
+    })
+  })
+
+  itWm('maximize and unmaximize toggle the maximized state', async () => {
+    await tauri((api) => api.window.getCurrentWindow().maximize())
+    await eventually(async () => {
+      if (
+        !(await tauri((api) => api.window.getCurrentWindow().isMaximized()))
+      ) {
+        throw new Error('window is not maximized')
+      }
+    })
+    await tauri((api) => api.window.getCurrentWindow().unmaximize())
+    await eventually(async () => {
+      if (await tauri((api) => api.window.getCurrentWindow().isMaximized())) {
+        throw new Error('window is still maximized')
+      }
+    })
+  })
+
+  itWm('setFullscreen toggles fullscreen', async () => {
+    await tauri((api) => api.window.getCurrentWindow().setFullscreen(true))
+    await eventually(async () => {
+      if (
+        !(await tauri((api) => api.window.getCurrentWindow().isFullscreen()))
+      ) {
+        throw new Error('window is not fullscreen')
+      }
+    })
+    await tauri((api) => api.window.getCurrentWindow().setFullscreen(false))
+    await eventually(async () => {
+      if (await tauri((api) => api.window.getCurrentWindow().isFullscreen())) {
+        throw new Error('window is still fullscreen')
+      }
+    })
+  })
+
+  itWm('setFullscreenOnMonitor goes fullscreen on that monitor', async () => {
+    // Use the monitor the window is on, so the assertion holds on single-monitor CI.
+    const origin = await tauri(async (api) => {
+      const monitor = await api.window.currentMonitor()
+      return monitor ? { x: monitor.position.x, y: monitor.position.y } : null
+    })
+    expect(origin).not.toBeNull()
+
+    await tauri(
+      (api, origin) =>
+        api.window
+          .getCurrentWindow()
+          .setFullscreenOnMonitor(
+            new api.dpi.PhysicalPosition(origin.x, origin.y)
+          ),
+      origin!
+    )
+    await eventually(async () => {
+      const state = await tauri(async (api) => {
+        const w = api.window.getCurrentWindow()
+        const position = await w.outerPosition()
+        return {
+          fullscreen: await w.isFullscreen(),
+          x: position.x,
+          y: position.y
+        }
+      })
+      if (!state.fullscreen) {
+        throw new Error('window is not fullscreen')
+      }
+      // a fullscreen window sits at its monitor's origin
+      if (state.x !== origin!.x || state.y !== origin!.y) {
+        throw new Error(
+          `window is at (${state.x}, ${state.y}), expected (${origin!.x}, ${origin!.y})`
+        )
+      }
+    })
+
+    await tauri((api) => api.window.getCurrentWindow().setFullscreen(false))
+    await eventually(async () => {
+      if (await tauri((api) => api.window.getCurrentWindow().isFullscreen())) {
+        throw new Error('window is still fullscreen')
+      }
+    })
+  })
+
+  itWm('hide and show toggle visibility', async () => {
+    await tauri((api) => api.window.getCurrentWindow().hide())
+    await eventually(async () => {
+      if (await tauri((api) => api.window.getCurrentWindow().isVisible())) {
+        throw new Error('window is still visible')
+      }
+    })
+    await tauri((api) => api.window.getCurrentWindow().show())
+    await eventually(async () => {
+      if (!(await tauri((api) => api.window.getCurrentWindow().isVisible()))) {
+        throw new Error('window is not visible')
+      }
+    })
+  })
+})

packages/api-e2e/test/types/global.d.ts

@@ -0,0 +1,17 @@
+// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+// The examples/api app is built with `withGlobalTauri: true`, so the whole
+// `@tauri-apps/api` surface is available on `window.__TAURI__` inside the webview.
+// This mirrors that for the functions we serialize and run in the page.
+
+import type * as TauriApi from '@tauri-apps/api'
+
+declare global {
+  interface Window {
+    __TAURI__: typeof TauriApi
+  }
+}
+
+export {}