Device conditions

A spec can put the device into a condition (offline, 3G, one host failing, a moving GPS fix, a clock two weeks ahead, a failed Face ID, a denied permission, a QR code in front of the camera) and check what the app does. Everything a test changes belongs to its lease: when the test ends, or the lease is released or reclaimed, warden puts it back, so the next agent never inherits a shaped device.

import { expect, test } from "@delacour/warden-e2e";

test("cold start offline shows the banner, going online recovers the fetch", async ({ app, device, screen }) => {
  await device.network.set("offline"); // before the app opens: a cold start offline
  await app.open();
  await expect(screen.getByTestId("conditions-offline-banner")).toBeVisible({ timeout: 15_000 });

  await device.network.set("online");
  await expect(screen.getByTestId("conditions-offline-banner")).toBeHidden({ timeout: 15_000 });
});

The example app has a Conditions screen (warden-example://conditions) and a spec for each area in apps/example/e2e.

Conditions

Platform support

Simulators and emulators only: every condition fails E_UNSUPPORTED on a physical device.

On iOS, network and clock reach only an app launched with warden's network dylib: declare them in the suite's conditions, or pass { relaunch: true } (how it reaches the app).

Three places to set one

The same conditions are available from a spec, as a suite's starting state, and by hand while you drive a device.

await device.network.set("3g");
await device.location.scenario("city-run");
await device.clock.advance("15d");
await device.permissions.set({ location: "denied" });

Suite baseline: the conditions key

conditions at the top level of warden.config.ts, or inside a suite, is the device state every spec starts from. It is applied before the app launches and put back after each spec.

e2e: {
  conditions: {
    ...exampleSuite,
    include: ["{network-*,location-*,clock-*}"],
    conditions: { network: "online" },
  },
},

A suite's key replaces the top-level one for that area. A bad value fails config load. On iOS, declaring network or clock launches the app with the dylib, which is why the example runs its condition specs in a separate conditions suite: the other specs keep a plain launch.

warden e2e conditions --specs network-offline,network-slow,location-route,clock-trial

The camera feed is the suite's own camera key, not a conditions key (Camera). Biometrics is not one either: enrolled devices come from biometrics: true (Biometrics).

Timeline

const run = await device.timeline([
  { at: "0s", network: "offline" },
  { at: "5s", network: "online", location: { lat: 37.33, lon: -122.0 } },
]);

A timeline changes the network and the location on a schedule. at is an offset from now. A step sets a condition, not a flap. The returned run has the same stop(), done and status() as a flap.

What is undone on release

Release, gc and the end of a spec put the device back:

• network online, faults cleared, the shaping proxy, the flap scheduler and the route ticker stopped
• the location cleared on iOS (Android keeps the last GPS fix: the emulator cannot unset one)
• the clock real again; a still-running injected iOS app is reset to online and the real clock
• permissions reset, text size and contrast or font scale and bold back to defaults, the app locale cleared, the timezone back, the battery real, the camera feed off

Each change a spec makes is a condition line in results.jsonl.