Skip to main content

Projects

A project is a named group of tests that run with one use configuration: a platform, a device, an app build, and the artifact settings that go with them. Projects are how you run the same specs on Android and iOS, on a local emulator and a cloud device, or against different environments, all from a single config.

Configure projects for multiple platforms​

List your projects in the projects[] array of taqwright.config.ts. Each project requires a name and its own use block. Unlike Playwright there is no top-level shared use, so factor values you want to share into a local constant:

taqwright.config.ts
import { defineConfig, Platform } from '@taqwright/taqwright';

const shared = {
  appium: { autoStart: true, host: 'localhost', port: 4723, path: '/' },
  resetBetweenTests: true,
} as const;

export default defineConfig({
  projects: [
    {
      name: 'android',
      use: {
        ...shared,
        platform: Platform.ANDROID,
        device: { provider: 'emulator', name: 'taqwright_api34' },
        buildPath: './app/DemoApp-v1.0.0.apk',
        appBundleId: 'com.taqelah.demo_app',
      },
    },
    {
      name: 'ios',
      use: {
        ...shared,
        platform: Platform.IOS,
        device: { provider: 'emulator', name: 'iPhone 17 Pro' },
        buildPath: './app/DemoApp-v1.0.0.app',
        appBundleId: 'com.taqelah.demoApp',
      },
    },
  ],
});

Every use block must carry at least platform and device. See Configuration for the full list of use options and more example projects (local emulators, BrowserStack, LambdaTest).

Run projects​

By default taqwright test runs every project. Pass --project to run a subset; the flag is repeatable:

# Run all projects
npx taqwright test

# Run one project
npx taqwright test --project android

# Run several
npx taqwright test --project android --project ios

See Command line for the rest of the test flags.

Configure projects for multiple environments​

Because each project owns its use, you can point projects at different devices or app builds, and drive the choice from the environment:

taqwright.config.ts
import { defineConfig, Platform } from '@taqwright/taqwright';

export default defineConfig({
  projects: [
    {
      name: 'local',
      use: {
        platform: Platform.ANDROID,
        device: { provider: 'emulator', name: 'taqwright_api34' },
        buildPath: './app/DemoApp-v1.0.0.apk',
        appBundleId: 'com.taqelah.demo_app',
        resetBetweenTests: true,
      },
    },
    {
      name: 'cloud',
      use: {
        platform: Platform.ANDROID,
        device: { provider: 'browserstack', name: 'Google Pixel 8', osVersion: '14.0' },
        buildPath: process.env.BS_APP_ID ?? 'bs://<app-id>',
        appBundleId: 'com.taqelah.demo_app',
        resetBetweenTests: true,
      },
    },
  ],
});

Cloud credentials are read from the environment (BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY, and the LambdaTest equivalents), never from config. See Parameterize tests for more on environment-driven config and .env files.

Splitting tests into projects​

Each project can narrow which specs it runs with testMatch, testIgnore, and testDir (inherited from the top-level config when omitted). A common use is a fast smoke project:

taqwright.config.ts
export default defineConfig({
  projects: [
    {
      name: 'smoke',
      testMatch: /.*\.smoke\.spec\.ts/,
      use: {
        platform: Platform.ANDROID,
        device: { provider: 'emulator', name: 'taqwright_api34' },
        buildPath: './app/DemoApp-v1.0.0.apk',
        appBundleId: 'com.taqelah.demo_app',
        resetBetweenTests: true,
      },
    },
    {
      name: 'full',
      testIgnore: /.*\.smoke\.spec\.ts/,
      use: {
        platform: Platform.ANDROID,
        device: { provider: 'emulator', name: 'taqwright_api34' },
        buildPath: './app/DemoApp-v1.0.0.apk',
        appBundleId: 'com.taqelah.demo_app',
        resetBetweenTests: true,
      },
    },
  ],
});
npx taqwright test --project smoke

Dependencies​

A project can declare dependencies: ['<project-name>']. Those projects run to completion before the dependent project starts, which is how you run a one-time setup (sign in, seed a backend) ahead of the suite:

taqwright.config.ts
export default defineConfig({
  projects: [
    {
      name: 'setup',
      testMatch: /global\.setup\.ts/,
      use: {
        platform: Platform.ANDROID,
        device: { provider: 'emulator', name: 'taqwright_api34' },
        buildPath: './app/DemoApp-v1.0.0.apk',
        appBundleId: 'com.taqelah.demo_app',
      },
    },
    {
      name: 'android',
      dependencies: ['setup'],
      use: {
        platform: Platform.ANDROID,
        device: { provider: 'emulator', name: 'taqwright_api34' },
        buildPath: './app/DemoApp-v1.0.0.apk',
        appBundleId: 'com.taqelah.demo_app',
        resetBetweenTests: true,
      },
    },
  ],
});

A setup project is a real taqwright spec, so it has the mobile fixture and can drive the device. See Global setup and teardown for the full walkthrough.

Running sequence​

Dependencies resolve before dependents: the setup project runs first, then every project that depends on it runs (in parallel with each other, subject to your worker count). If a dependency fails, its dependents are skipped.

Teardown​

taqwright projects do not take a project-level teardown property. For end-of-run cleanup, use the top-level globalTeardown option, which runs once after all projects and tests finish. See Global setup and teardown.

Test filtering​

Filters like --grep, --shard, and test.only select your primary tests; the dependencies of whatever is selected still run, so a setup project executes even when you filter down to one test:

npx taqwright test --project android --grep @checkout
# the `setup` dependency still runs first

Per-project options​

These fields can be set per project. The first group overrides the top-level config when present; the second group is project-only.

FieldNotes
testDirOverrides the top-level test directory.
testMatch / testIgnoreNarrow which specs this project runs.
timeoutPer-test timeout for this project, in ms.
retriesRetry count for this project.
outputDirWhere this project writes artifacts.
nameRequired. The project name used by --project.
useRequired. The mobile config (platform, device, app, artifacts).
grep / grepInvertFilter tests by title / @tag within the project.
dependenciesOther project names to run first.
workersParallel workers for this project. See Parallelism.

See Configuration for the complete use reference.