Testing

olan-app test runs tests/**/*.test.ts with Node's test runner (node:test). Each test renders the app headlessly with renderApp from @olan-app/cli/testing: your real src/app.tsx, the real SDK runtime and React reconciler, against a mock Olan host that answers olan.* from fixtures and enforces permissions exactly like Olan. No browser, no screenshots: you assert on text, the UI tree and the recorded olan.* calls.

import assert from 'node:assert/strict';
import { test } from 'node:test';

import { renderApp } from '@olan-app/cli/testing';

test('lists projects and opens one', async () => {
  const app = await renderApp({ surface: 'app' });
  app.expectText('Web sitesi');
  await app.press('Web sitesi');                       // List item title
  assert.deepEqual(app.navigation(), [{ action: 'push', screen: 'project', params: { projectId: 'p0' } }]);
  app.expectText('Görev 2');
  await app.dispose();
});

Run: npx olan-app test (all), npx olan-app test overdue (files whose path contains overdue), --json for a summary { files, tests, passed, failed, skipped, durationMs, failures }. Set OLAN_APP_TEST_LOGS=1 to print the app's console.* output. Always await app.dispose().

For Olan Marketplace: npx olan-app test --report test-report.json packs the app first (like pack, into .olan-app/report/), runs the whole suite (no pattern) and writes a report bound to that package's digest.package and signed with your development key; failing runs write it too and exit 1. Make it after your last source change and attach it with publish --marketplace --test-report test-report.json (marketplace.md#signed-test-reports).

renderApp(options?) #

Bundles the app (cached per run), boots the runtime, opens the surface and resolves after the first render and its olan.* calls have settled. It throws if the surface reports an error (unless allowErrors: true).

The rendered app #

"Visible text" includes Text, titles and subtitles, List titles/subtitles/meta/badges, empty texts, Table headers and cells, Badge, Button and Menu labels, field labels and values, EmptyState texts and Chart series names; also Tabs labels, Switch labels and descriptions, the MultiSelect label and the selected options' labels (else its placeholder), Stat label, raw value (1250.5, not the formatted text; null is "—") and caption, Banner title, text and action label, and the ProgressBar label. Image and Avatar add no text (check them with find). Menu items are not visible until opened, but press('<item label>') selects them; press also selects a Tabs item (by label) and a Banner action; dismiss(text?) closes a Banner.

Recorded method names #

calls(method) filters by RPC name, the olan.* path without olan.:

const params = app.calls('db.insert')[0]!.params as { collection: string; data: { title: string } }; // JsonValue → cast
assert.equal(params.data.title, 'Rapor');
const task = app.calls('projects.createTask')[0]!.result as { id: string; title: string };
const items = app.find('List')[0]!.props.items as unknown as { key: string; title: string }[]; // PropValue → cast
assert.equal(items[0]!.title, 'Görev 1');

Tests are type-checked: olan-app validate (also with --strict) runs tsc --noEmit on tsconfig.json and tests/tsconfig.json, so a missing cast is a typescript.* error there. olan-app test only bundles the tests and does not type-check.

host.data #

Mutating app.host.data changes what the next olan.* call returns:

app.host.data.http[URL] = { status: 200, json: { services: [] } };
await app.press('Tekrar dene');

Fixtures #

The mock host serves, key by key: renderApp({ fixtures }) over fixtures/*.json over the built-in data. Built-in projects: p0 "Web sitesi", p1 "Mobil uygulama", p2 "Ofis taşınması", each with tasks <id>-t0…<id>-t3 titled "Görev 1"…"Görev 4", due 2026-10-10…2026-10-13, the first completed and the rest needs-action. No chats, storage, settings or HTTP responses by default. Calendar: cal-0 (default) with ev-0 (the user organizes it), ev-meeting (an Olan meeting, UID mt-0@olan.app, protected) and ev-invite (an invitation), and the project calendar cal-p0 (ev-p0, protected). Contacts: ab-0 (own, default) with ct-0, ab-company (shared, read-only) with ct-company. Mail: mail-0 "Teklif hakkında". Meetings: mt-0. A key you provide replaces the built-in one entirely (e.g. your projects replace all three).

Missing task fields get defaults: status: "needs-action", due: null, revision: 1, assigneeId: null, description: "", createdBy: the default user, listId = the first list. Projects without "members" get [{ "userId": <default user>, "displayName": "Utku", "role": "owner" }]; without "lists", one list { "id": "<projectId>-l0", "name": "Görevler" }. A projects.json entry may give "lists" and "members", or use the ProjectDetail shape { "project", "members", "lists", "tasks" }.

SDK 1.6 (project extensions): every fixture project has the app enabled unless it says "enabled": false: such a project is left out of olan.projects.list, and calls naming it fail with project_not_enabled, as on a server. "config": { … } is the stored olan.project.config value (revision 1); after a set the mock host keeps the new one in app.host.data.projectConfigs[projectId].

SDK 1.7: every fixture project has the default statuses todo "Yapılacak", in_progress "Devam ediyor", done "Tamamlandı" and cancelled "İptal" (ids <projectId>-status-<key>); its tasks start on the one of their status. A project may add what the app already contributed — each the app's own unless it says "app": false:

{ "id": "office", "name": "Ofis", "taskKeyPrefix": "OFS",
  "issues": [{ "id": "i1", "title": "Klima bozuk", "number"?: 1, "state"?: "open", "inTriage"?: false }],
  "statuses": [{ "key": "awaiting-approval", "name": "Onay bekliyor", "category": "started", "color"?: "#E0A526" }],
  "labels": [{ "key": "hardware", "name": "Donanım", "groupName"?: "Tür" }],
  "fields": [{ "key": "size", "name": "Boyut", "type": "select", "options"?: [{ "id"?: "large", "name": "Büyük" }], "required"?: false, "appliesTo"?: ["task"] }],
  "fieldValues": [{ "target": { "kind": "task", "id": "t1" }, "values": { "size": "large" } }],
  "links": [{ "id": "link-1", "target": { "kind": "task", "id": "t1" }, "externalId": "SAT-7", "card": { …record card… } }],
  "calendarItems": [{ "externalId": "SAT-7", "title": "Teslim", "start": "2026-11-10", "linkId"?: "link-1" }],
  "approvals": [{ "id": "a1", "title": "SAT-7 onayı", "approverIds": ["<member id>"], "mode"?: "any", "state"?: "pending", "linkId"?: "link-1" }] }

The mock host answers olan.project.* with the server's checks and codes (keys, taken names, record cards that only open, limits, approvers who are project members other than guest). app.host.decideApproval(projectId, approvalId, 'approve' | 'reject', { userId?, note? }) decides as an approver would (any: the first decision; all: a rejection or the last approval). Links, calendar items and approvals carry the manifest's id and name (appId, name) and installationId: MOCK_INSTALLATION_ID.

Surface params in tests #

Without params, renderApp builds what the host would send from the (merged) fixtures:

mail.getMessage answers only for the current messageId (others: permission_denied) and needs the entry in mail.json (not_found otherwise). Test another email with renderApp({ surface: 'mail.sidebar', fixtures: { mail: [{ id: 'm1', subject: 'Fatura', from: { name: null, email: 'muhasebe@firma.com' } }] } }) or, in an open panel, await app.setParams({ ...params, messageId: 'm1' }).

Users: the signed-in user is DEFAULT_USER_ID = 00000000-0000-4000-8000-000000000001, "Utku" (utku@example.com; exported with DEFAULT_USER from @olan-app/cli/testing); renderApp({ userId }) changes it (useUser().id follows). olan.users.get answers from the default user plus fixtures/users.json; other ids are left out. Other people: add them to users.json, list them in a project's members, seed rows with their createdBy, or act as them with app.host.db.as(id).

Ids: the built-in project, task and list ids (p0, p0-t0, p0-l0) are not UUIDs, but ref:project, ref:task and ref:user fields accept only UUIDs (validation_failed). If the app stores such ids in olan.db, give fixtures/projects.json UUID ids (and members with UUID userIds). fixtures/db.json row ids may be any unique non-empty string ("d1"); rows the app inserts get UUIDs, as in Olan, so do not depend on the id format.

HTTP fixtures match "METHOD url" first, then the exact url, then the URL without its query string. A URL without a fixture answers http_blocked (the mock never touches the network); validate --strict warns fixtures.http_missing for it. json sets the body to JSON.stringify(json) and content-type: application/json.

The mock host also applies Olan's rules: missing permission → permission_denied, HTTP host not in permissions → http_blocked, a stale revision → conflict, storage values > 64 KiB → invalid_params. olan.db runs on the same in-memory database Studio uses (@olan-app/sdk/memory-db), with the server's validation, rules, cursors, quota and error codes (renderApp({ userId, quota }) changes the signed-in user and the limits). The first work package of each mock project is the default one (isDefault: true): deleteList on it, or on a non-empty one, fails with forbidden_record, as on the server.

Remote requests, files and links #

olan.remote.request goes to a mock app server: renderApp({ remote }) (or app.remote(…)), else the fixtures/remote.json answers. Routes use the handleRequest format and rules (remote-requests.md): :name and /* parameters, unknown route 404, other method 405, a thrown RequestError its status, any other throw 500. The answer goes through the same mapping as in Olan: 200–399 resolve, 4xx reject remote_rejected, 5xx and no handler remote_unavailable, and the call waits at most its timeoutMs. Without "requests": true in the manifest every call fails with permission_denied.

import { remote, renderApp, RequestError } from '@olan-app/cli/testing';

const items = [{ id: 'm1', title: 'Lansman', status: 'ready', url: 'http://127.0.0.1:4419/olan/media/m1' }];
const app = await renderApp({
  remote: remote({
    'GET /items': () => ({ body: items }),
    'POST /items': (ctx) => ({ status: 201, body: { item: { id: 'm2', ...(ctx.body as object) }, upload: { url: 'http://127.0.0.1:4419/olan/uploads/m2?token=t' } } }),
    'DELETE /items/:id': (ctx) => { if (ctx.params.id !== 'm1') throw new RequestError(404, { error: 'item_not_found' }); },
  }),
  ui: { files: ['kampanya.jpg'] },                       // fixtures/files.json names or inline { name, type, size, content }
  upload: (upload) => ({ status: 201, headers: { etag: '"1"' }, body: { id: 'm2' } }),
  profileRole: 'admin',
});
await app.press('Yükle');                                // Tabs item
const [sent] = app.host.remoteRequests;                  // { envelope, answer }
assert.equal(sent!.envelope.user?.email, 'utku@example.com');   // only with profile:read
assert.equal(app.host.uploads[0]!.headers['x-olan-file-name'], 'kampanya.jpg');
await app.fireTimers();                                  // a useQuery refetchIntervalMs tick

• Envelopes. host.remoteRequests holds { envelope, answer } per call: envelope is the signed body Olan would post (issuer MOCK_ISSUER https://olan.test, installation MOCK_INSTALLATION_ID, user.organizationId DEFAULT_ORGANIZATION_ID, locale tr, timeZone Europe/Istanbul, a placeholder token); with profile:read the user gets email and displayName from the users fixtures and role from profileRole. answer is the wrapper the route returned (null when there was none).

• Errors in the app. app.calls('remote.request')[0]!.error is { code, message, details } (details: { status, body?, reason? }); in the app it is a RemoteError. Throw RequestError in test routes, imported from @olan-app/cli/testing or @olan-app/sdk/server (your server's own routes work as they are).

• Files. The picker returns the fixtures/files.json files (default: all that accept and maxBytes allow, up to maxFiles); ui.files chooses (['tanitim.mp4'], inline entries, null/[] = cancelled, or (options) => …). Uploads must target the manifest remote.url origin or an http:<host> permission (http_blocked); http://127.0.0.1 works because tests are a development installation. onProgress gets { loaded: 0 } at the start and { loaded: size } at the end.

• Upload types (exported from @olan-app/cli/testing). host.uploads and the upload handler's argument are MockUpload: { uploadId: 'upl_…', file: FileHandle & { content: string }, url, method: 'PUT' | 'POST', headers: Record<string, string>, formField: string | null, fields: Record<string, string>, status: 'running' | 'done' | 'cancelled' | 'failed' }. file.content is the fixture file's content text ('' when it has none); headers are what the target got, lower-case (content-type, content-length for PUT, x-olan-file-name, yours). The handler returns MockUploadAnswer = { status?: number, headers?: Record<string, string>, body?: JsonValue } (only content-type, etag, location reach the app); its type is MockUploadHandler.

• Cancelling an upload. press resolves only when everything it started has settled, and a running upload has not. Start the press without awaiting it, wait for the progress UI, press cancel, then await the first press:

  const app = await renderApp({ ui: { files: ['tanitim.mp4'] }, upload: () => new Promise(() => {}) });  // never answers
  const uploading = app.press('Yükle');                       // not awaited yet
  await app.waitFor((view) => view.find('ProgressBar').length > 0);
  await app.press('İptal');                                   // task.cancel(): the upload rejects with `cancelled`
  await uploading;                                            // now it settles
  assert.equal(app.host.uploads[0]!.status, 'cancelled');
  

  Awaiting press('Yükle') directly fails after timeoutMs with "files.upload is still pending"; the same pattern works for a slow remote route (return a promise you resolve later).

• Without profile:read. The envelope's user has only id, organizationId, locale and timeZone. Leave the permission out of the list to test what your server does then (remote stays granted):

  const app = await renderApp({ permissions: ['files:pick'], remote: remote({ 'GET /me': (ctx) => ({ body: { email: ctx.user?.email ?? null } }) }) });
  assert.equal(app.host.remoteRequests[0]!.envelope.user?.email, undefined);
  

• Testing your server. createTestIssuer and signRemoteRequest sign requests exactly as Olan does, for tests of the app server itself (remote-requests.md#testing-the-app-server).

• Links. host.opened lists { url, external, expectReturn }. ui.openExternal answers openExternal(…, { expectReturn: true }) (e.g. { returned: true, params: { state: 'st_1' } }). A return without a pending call is renderApp({ params: { return: { state: 'st_1' } } }).

• App addresses. renderApp({ navigation: { screen: 'item', params: { id: 'm1' } } }) opens on item over index (app.back() returns to index); screen: 'index' gives the first screen these params.

• Refresh. The mock host never ticks by itself: host.timers() lists the running { timerId, intervalMs } (at least 5000) and app.fireTimers() sends one tick to each.

• Switches and multi-selects. await app.toggle('Hemen yayınla'), await app.select('Kanallar', ['instagram', 'tiktok']) (or one value to toggle it).

• Banners. await app.press('Yeniden bağla') presses a Banner action; await app.dismiss('Bağlantının süresi doldu') presses its close button (onDismiss).

Backend tests #

Backend code (server, backend.md) is tested headlessly with createBackendHarness: it bundles server.entry, runs it in @olan-app/runtime (isolated-vm in a forked runtime process, or QuickJS with olan-app test --engine quickjs) and answers olan.* from the same mock host as renderApp (in-memory olan.db, fixtures/*.json, fixtures/http.json for olan.http.fetch). Name the files tests/*.backend.test.ts (any *.test.ts runs).

import { createBackendHarness, signHookRequest } from '@olan-app/cli/testing';

test('digest', async () => {
  const backend = await createBackendHarness({ secrets: { apiToken: 't' }, now: '2026-10-17T09:00:00Z' });
  try {
    const summary = await backend.call<{ count: number }>('summary', { limit: 5 });   // { ok, value | error, logs, cpuMs, wallMs }
    assert.equal(summary.ok, true, summary.error?.message);
    await backend.runSchedule('digest', { scheduledAt: '2026-10-17T09:05:00Z' });
    await backend.emit({ type: 'project.task.created', data: { projectId: 'p0', task: { id: 't1', title: 'Yeni' } } });
    const hook = await backend.hook('github', { headers: { 'x-github-event': 'push' }, body: { ref: 'refs/heads/main' } });
    assert.equal(hook.status, 200);                                   // signed with the secret setting for you
    const forged = await backend.hook('github', { headers: { 'x-hub-signature-256': 'sha256=00' }, body: '{}' });
    assert.equal(forged.status, 401);                                 // the function did not run
    assert.equal(backend.calls('http.fetch')[0]?.ok, true);           // olan.* calls the backend made
  } finally {
    await backend.dispose();                                          // always: it stops the runtime
  }
});

Methods: call(name, args?, { userId?, permissions? }) (actor user), runSchedule(name, { scheduledAt? }), emit(type | { type, data?, actor?, id? }) (only events in server.events; default data from the fixtures), hook(name, { method?, headers?, body?, query?, sign? }) (returns { status, headers, body, verified } plus the result; sign: false sends it unsigned), migrate(fromVersion), calls(method?) (only the backend's calls), logs(), host, db, manifest, engine, dispose(). Results: { ok, value?, error?: { code, runtimeCode, message }, logs, cpuMs, wallMs } — code is what olan.backend.call rejects with (backend_error, backend_limit, …), runtimeCode the runtime's (handler_error, cpu_limit, …).

hook() bodies: a string is sent as is; any other JSON value as JSON.stringify(body) with content-type: application/json (signed over those exact bytes). await signHookRequest(verify, body, secret) is async and returns the headers to send: { [verify.header]: 'sha256=<lower-case hex>' } for hmac-sha256, webhook-id/webhook-timestamp/webhook-signature for standard-webhooks; verifyHookSignature checks one by hand.

Recorded calls (backend.calls(), renderApp().calls(m, { source: 'backend' })): params is the RPC object, e.g. http.fetch → { url, method?, headers?, body? }. Secret values never appear: a secrets.get result is "[secret]", and every occurrence of a secret value (4+ characters) in params, results and errors is replaced by "[secret]" (headers.authorization → 'Bearer [secret]'). host.handle() and the backend itself still get the real values. fixtures/settings.json holds dev-only secrets (never real ones): it is used by tests, validate and dev, and is not packed.

Patterns #

// project.widget with params
const app = await renderApp({ surface: 'project.widget', params: { projectId: 'site' }, now: '2026-10-20T09:00:00Z' });

// a write: check the call and the new state
await app.press('Görev 2');
await app.press('Tamamlandı');                                   // Menu item
assert.equal(app.calls('projects.updateTask')[0]?.ok, true);
assert.equal(app.host.data.projects[0]!.tasks[1]!.status, 'completed');

// dialogs
const app2 = await renderApp({ ui: { confirm: false, prompt: (params) => 'Yeni ad' } });

// storage
const app3 = await renderApp({ fixtures: { storage: { currency: 'EUR' } } });
assert.deepEqual(app3.host.data.storage, { currency: 'EUR' });

// forms
await app.fill('Başlık', 'Rapor');
await app.select('Durum', 'completed');
await app.press('Kaydet');                                        // Form submitLabel (or a Button)

// permissions
const denied = await renderApp({ permissions: [] });
assert.equal(denied.calls('projects.list')[0]?.error?.code, 'permission_denied');

Test files are bundled with esbuild for Node, so TypeScript works without a separate compiler. Import only node:* modules, @olan-app/cli/testing, @olan-app/sdk/server (server tests), your app server's modules (../app-server/routes.ts) and your own helpers; do not import src/app.tsx into tests (renderApp loads it). After a file's tests end, its process gets 1.5 s to exit by itself; a crash after every test passed is reported as test.process_crashed (a warning), not as a failed test.