Quick Start

1. Install

npm install spana-test
# or
bun add spana-test

spana works with Node.js 20+ and Bun.

2. Create a config file

Create spana.config.ts at the root of your project:

import { defineConfig } from "spana-test";

export default defineConfig({
  apps: {
    web: { url: "http://localhost:3000" },
    android: { packageName: "com.example.app" },
    ios: { bundleId: "com.example.app" },
  },
  platforms: ["web"],
});

Start with platforms: ["web"] while getting familiar with the framework, then add "android" and "ios" once your device targets are set up.

3. Write a flow

Create flows/login.ts:

import { flow } from "spana-test";

export default flow("user can log in", async ({ app, expect }) => {
  await app.tap({ testID: "email-input" });
  await app.inputText("user@example.com");
  await app.tap({ testID: "password-input" });
  await app.inputText("secret");
  await app.tap({ testID: "login-button" });
  await expect({ testID: "home-screen" }).toBeVisible();
});

The testID selector maps to data-testid on web, accessibilityIdentifier on iOS, and resource-id on Android. It is the preferred selector type.

4. Run

spana test

This discovers all *.ts files under ./flows (or the flowDir in your config) and runs them against the configured platforms.

Run a single file

spana test flows/login.ts

Target a specific platform

spana test --platform android

Filter by tag

spana test --tag smoke

5. View results

By default, results print to the console. To get structured JSON output:

spana test --reporter json

On failure, spana captures a screenshot and UI hierarchy dump under .spana/artifacts/ (configurable via artifacts.outputDir).

Next steps

• Configuration — all defineConfig options
• Flows — flow() API, tags, timeouts
• Selectors — all selector types
• CLI Commands — all flags