Files
simplex-chat/apps/ios
Evgeny @ SimpleX Chat 73761e6e0b core, ui: test app views on the core's recorded responses (#8234)
* core, ui: plan name alert tests against core fixtures

* core: write name lookup responses to app fixtures in name tests

* android, desktop: name alerts tested against core fixtures

* core, ios: plan Swift fixtures and iOS unit tests of name alerts

* core: write name lookup responses in the Swift form to iOS fixtures

* ios: name alerts tested against core fixtures

* core: write both app fixtures of a name test in one run

* ui: add name lookup responses written by the core tests as fixtures

* core: keep the fixture writer of name tests to the forms it receives

* desktop: run name alert tests in the US locale

* ios: one switch for the title and effect of name alert actions

* docs: name alert tests in the app specs, CI guide and plan

* docs: known gaps of the name alert tests in the plan

* ui: restore the name alert code and the iOS project of master

* core: record name lookup responses and name parses for app tests

* android, desktop: test name alerts of planAndConnect on recorded responses

* ci: run the app tests for a change of the name fixtures

* core: name lookup responses and name parses recorded by the core tests

* docs: plan of app views tested on core responses

* ios: test name alerts of planAndConnect on recorded responses

* ci: iOS unit tests in the iOS job, the app launched on stub migrations

* android, desktop: core hooks below the externals, in the specs

* ios: name alert tests compile with the converter at file scope

* ui: the moved name test expects the alert to open a chat with the new address

* core, ui: app test fixtures under tests/fixtures/api

* core: record the responses of the name lookup flows that the apps test

* core: record URI parses, and normalize the random values of fixtures

* android, desktop: URI parse hook and event processing for tests

* ios: URI parse hook for tests

* desktop: full failure messages of tests

* core: domain errors view compiles with GHC 8.10.7

* core: normalize parses and profile send times in fixtures

* core: record the parses of the chat list search

* core: recorded responses of the name flows and the contact address

* android, desktop: test name alerts, buttons, search and name view

* ios: test name alerts, buttons, search and the moved event

* docs: plan, specs and CI guide of the app tests
2026-11-16 23:36:37 +00:00
..
2026-10-20 09:27:01 +01:00
2026-10-20 09:27:01 +01:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-10-20 09:27:01 +01:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-10-30 14:18:08 +00:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-10-30 14:18:08 +00:00
2026-10-20 09:27:01 +01:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00
2026-11-04 12:07:17 +00:00

SimpleX Chat iOS app

This file provides guidance when working with code in this repository.

iOS App Overview

The iOS app is a SwiftUI application that interfaces with the Haskell core library via FFI. It shares the SimpleXChat framework with two extensions: Notification Service Extension (NSE) for push notifications and Share Extension (SE) for sharing content from other apps.

Build & Development

Open SimpleX.xcodeproj in Xcode. The project has five targets:

  • SimpleX (iOS) - Main app (Bundle ID: chat.simplex.app)
  • SimpleXChat - Framework containing FFI bridge and shared types
  • SimpleX NSE - Notification Service Extension
  • SimpleX SE - Share Extension
  • Tests iOS - UI tests

Build and run via Xcode (Product > Build/Run). Tests run via Product > Test or:

xcodebuild test -scheme "SimpleX (iOS)" -destination 'platform=iOS Simulator,name=iPhone 15'

Deployment target: iOS 15.0+, Swift 5.0.

Architecture

Haskell Core Integration

The app calls the Haskell core library through C FFI defined in SimpleXChat/SimpleX.h:

  • chat_migrate_init_key() - Initialize/migrate database
  • chat_send_cmd_retry() - Send command to chat controller
  • chat_recv_msg_wait() - Receive messages from controller

Swift wrappers in SimpleXChat/API.swift:

  • chatMigrateInit() - Initialize chat controller
  • sendSimpleXCmd<R>() - Send typed commands and parse responses
  • recvSimpleXMsg<R>() - Receive typed messages

Haskell runtime initialization (SimpleXChat/hs_init.c) uses different memory configurations:

  • Main app: 64MB heap
  • NSE: 512KB heap (minimal footprint for background processing)
  • SE: 1MB heap

Pre-compiled Haskell libraries are in Libraries/{ios,mac,sim}/.

State Management

  • ChatModel (Shared/Model/ChatModel.swift) - Main singleton ObservableObject for app-wide state (chat list, active chat, users)
  • ItemsModel - Manages chat items within a selected chat (similar to Kotlin's ChatsContext)
  • AppTheme - Theme management and customization

App Structure

Entry point: Shared/SimpleXApp.swift

Key directories in Shared/:

  • Model/ - Data models and API layer (ChatModel.swift, SimpleXAPI.swift)
  • Views/ - SwiftUI views organized by feature:
    • ChatList/ - Chat list and user picker
    • Chat/ - Message display and composition
    • Call/ - VoIP call UI
    • UserSettings/ - App settings
    • LocalAuth/ - Passcode and biometric authentication
    • Database/ - Database initialization and migration

Shared Data Between Targets

All three targets share data via App Group (group.chat.simplex.app):

  • SimpleXChat/AppGroup.swift - GroupDefaults wrapper for typed shared preferences
  • Keychain for sensitive data: kcDatabasePassword, kcAppPassword, kcSelfDestructPassword

Key Types

Types are defined in SimpleXChat/:

  • ChatTypes.swift - User, Chat, Message, Group types
  • APITypes.swift - API request/response types

Commands follow ChatCmdProtocol (has cmdString property), sent as JSON through FFI.

Localization

31 languages supported. Localization files in SimpleX Localizations/.

Workflow:

  • Product > Export Localizations - Export XLIFF files
  • Product > Import Localizations - Import updated translations

SimpleX Assets

The app includes optional assets behind the SIMPLEX_ASSETS Swift compilation flag. Without setup, the app builds normally without them.

Setup

Create Local.xcconfig (gitignored) in the apps/ios/ directory:

SIMPLEX_ASSETS_DIR = /path/to/assets
SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) SIMPLEX_ASSETS

The copy script (scripts/ios/copy-assets.sh) runs as a build phase on each build but exits immediately if SIMPLEX_ASSETS is not set.

Updating assets

When source images change, regenerate resized images (requires ImageMagick):

cd path/to/assets && ./resize.sh

Background Capabilities

Configured in Info.plist:

  • Background modes: audio, fetch, remote-notification, voip
  • URL scheme: simplex:// for deep linking
  • BGTaskScheduler: chat.simplex.app.receive