# Receptury natywne: iOS i Android

URL: https://developertoolkit.ai/pl/cookbook/mobile-development/native-ios-android/
Description: Swift/SwiftUI i Kotlin/Compose z agentem: jeden skrypt build-i-test na platformę, pętle symulatora i emulatora, szybkie buildy i dowody z testów UI.

Natywny rozwój aplikacji na iOS i Androida z agentem AI działa wtedy, gdy każda platforma ma jeden skrypt, który buduje aplikację, uruchamia testy na przypiętym symulatorze lub emulatorze i zapisuje wyniki jako dowody. Claude Code, Codex i Cursor iterują względem tego skryptu, a serwer MCP, taki jak MobileBuildMCP lub mobile-mcp, pokazuje agentowi działającą aplikację.

Prosisz agenta o nowy ekran ustawień w SwiftUI. Agent pisze czysty kod w Swifcie, ogłasza „gotowe”, a projekt się nie buduje, bo nowy plik nigdy nie trafił do targetu Xcode. Po stronie Androida agent przy każdej zmianie odpala `./gradlew clean build`, czeka minutami na wynik i wkleja do własnego kontekstu tysiące linii logu Gradle. Żaden z nich nie spojrzał na ekran, który zbudował. Ta strona zamyka te trzy luki: informację zwrotną z builda, szybkość i dowód.

## Co daje projekt natywny przygotowany pod agenta

- Dwa skrypty do skopiowania, `scripts/ios-check.sh` i `scripts/android-check.sh`. Każdy uruchamia przypięte urządzenie, odpala testy, wypisuje agentowi krótkie podsumowanie i zapisuje pełne dowody w `build/evidence/`.
- Blok instrukcji do `AGENTS.md`, `CLAUDE.md` lub reguły Cursora, który definiuje „gotowe” jako „skrypt zakończył się kodem 0”.
- Zweryfikowane komendy instalacji dwóch mobilnych serwerów MCP oraz wtyczek Codeksa dla iOS i Androida, osobno dla każdego narzędzia.
- Zasady skracające wewnętrzną pętlę agenta: wąski wybór testów, rozgrzane urządzenia i cache.
- Receptury na ekran w SwiftUI, ekran w Jetpack Compose i reprodukcję crasha, każda zakończona dowodem z testów UI zamiast diffem do przeczytania.

## Dlaczego aplikacje natywne potrzebują innej pętli agenta

Agent webowy dostaje tanią informację zwrotną: serwer deweloperski przeładowuje się w sekundę, a przeglądarkowy MCP pokazuje stronę. Projekt natywny daje tę informację wolniej, z trzech powodów:

1. **Plik projektu jest częścią builda.** Xcode decyduje, co się kompiluje, na podstawie przynależności do targetu w `project.pbxproj`, a Gradle na podstawie układu modułów. Agent, który zapisze poprawny plik w złym miejscu, dostaje błąd builda albo, co gorsze, plik, który po cichu nigdy się nie kompiluje.
2. **Buildy są wolne i głośne.** Czysty `xcodebuild` albo build Gradle wypisuje tysiące linii. Wpuszczone do kontekstu agenta kosztują tokeny i wypychają z pola widzenia instrukcje zadania.
3. **UI działa w osobnym procesie.** Symulator i emulator to osobne programy. Bez runnera testów albo serwera MCP agent nie ma jak sprawdzić, czy ekran się renderuje. Ty też nie.

Dlatego receptury na tej stronie nie zaczynają się od promptu z funkcją. Zaczynają się od dania agentowi jednej, cichej i niezawodnej komendy na platformę, a agenta ocenia się po tym, co ta komenda udowadnia.

## Skonfiguruj pętlę: build, testy, dowody

1. **Przypnij jeden symulator i jeden emulator.** Dostępne urządzenia wypiszesz przez `xcrun simctl list devices available` i `emulator -list-avds` (binarka `emulator` leży w `$ANDROID_HOME/emulator`). Wybierz po jednym i wpisz ich nazwy do skryptów poniżej. Przypięte urządzenie oznacza, że czerwony test mówi coś o twoim kodzie, a nie o tym, który telefon agent akurat uruchomił.

2. **Dodaj `scripts/ios-check.sh`.** Skrypt trzyma DerivedData w repozytorium, zapisuje pełny log do pliku i wypisuje tylko linie potrzebne agentowi:

   ```bash
   #!/usr/bin/env bash
   # scripts/ios-check.sh — build, test and collect evidence on one pinned simulator.
   # Usage: scripts/ios-check.sh [TestTarget/TestClass ...]   (no argument = all tests)
   set -euo pipefail
   SCHEME="${SCHEME:-App}"
   SIM="${SIM:-iPhone 17}"
   OUT="build/evidence/ios"
   rm -rf "$OUT" && mkdir -p "$OUT"

   ONLY=()
   for t in "$@"; do ONLY+=("-only-testing:$t"); done

   xcrun simctl bootstatus "$SIM" -b >/dev/null   # boots the simulator if needed, waits until ready

   set +e
   xcodebuild test \
     -scheme "$SCHEME" \
     -destination "platform=iOS Simulator,name=$SIM" \
     -derivedDataPath build/DerivedData \
     -resultBundlePath "$OUT/tests.xcresult" \
     ${ONLY[@]+"${ONLY[@]}"} > "$OUT/xcodebuild.log" 2>&1
   STATUS=$?
   set -e

   xcrun xcresulttool get test-results summary --path "$OUT/tests.xcresult" > "$OUT/summary.json" 2>/dev/null || true
   grep -E "error:|\*\* (BUILD|TEST) (SUCCEEDED|FAILED)|failed" "$OUT/xcodebuild.log" | tail -40
   echo "exit=$STATUS evidence=$OUT"
   exit $STATUS
   ```

   Zapis `${ONLY[@]+...}` jest istotny: macOS nadal dostarcza Basha 3.2, w którym pusta tablica przy `set -u` przerywa skrypt. `xcresulttool get test-results` wymaga Xcode 16 lub nowszego.

3. **Dodaj `scripts/android-check.sh`.** Skrypt korzysta z już działającego emulatora, czyści logcat, żeby log obejmował tylko ten przebieg, i kopiuje raporty testów Gradle do katalogu z dowodami:

   ```bash
   #!/usr/bin/env bash
   # scripts/android-check.sh — unit + instrumented tests on one pinned emulator, evidence collected.
   # Usage: scripts/android-check.sh [com.example.app.SomeUiTest]   (no argument = all tests)
   set -euo pipefail
   AVD="${AVD:-Pixel_8_API_35}"
   MODULE="${MODULE:-app}"
   OUT="build/evidence/android"
   rm -rf "$OUT" && mkdir -p "$OUT"

   if ! adb get-state >/dev/null 2>&1; then
     emulator -avd "$AVD" -no-window -no-audio -no-boot-anim > "$OUT/emulator.log" 2>&1 &
     adb wait-for-device
     until [ "$(adb shell getprop sys.boot_completed | tr -d '\r')" = "1" ]; do sleep 2; done
   fi
   adb logcat -c

   FILTER=()
   if [ $# -gt 0 ]; then FILTER=("-Pandroid.testInstrumentationRunnerArguments.class=$1"); fi

   set +e
   ./gradlew ":$MODULE:testDebugUnitTest" ":$MODULE:connectedDebugAndroidTest" \
     ${FILTER[@]+"${FILTER[@]}"} > "$OUT/gradle.log" 2>&1
   STATUS=$?
   set -e

   adb logcat -d > "$OUT/logcat.txt"
   cp -R "$MODULE/build/reports" "$OUT/reports" 2>/dev/null || true
   cp -R "$MODULE/build/outputs/androidTest-results" "$OUT/androidTest-results" 2>/dev/null || true
   grep -E "FAILED|BUILD (SUCCESSFUL|FAILED)|e: " "$OUT/gradle.log" | tail -40
   echo "exit=$STATUS evidence=$OUT"
   exit $STATUS
   ```

   Opcjonalny argument zawęża do jednej klasy tylko testy instrumentacyjne. Testy jednostkowe zawsze idą w całości, bo są tanie.

4. **Przekaż agentowi zasady.** Wklej ten blok do `AGENTS.md` dla Codeksa, do `CLAUDE.md` dla Claude Code albo do reguły projektu w Cursorze. Claude Code czyta `AGENTS.md`, gdy w repozytorium nie ma `CLAUDE.md` (od v2.1.277, oba kanały wydań, stan na 2026-10-12), więc jeden plik może obsłużyć oba CLI. Jeśli nie pisałeś jeszcze pliku instrukcji, zacznij od artykułu [AGENTS.md i CLAUDE.md](/pl/developer-scorecard-guide/claude-md-context/):

   ```markdown
   ## Native build and test loop
   - iOS: run `scripts/ios-check.sh`, optionally with a test class such as `AppUITests/SettingsUITests`.
     Never call `xcodebuild` without `-derivedDataPath build/DerivedData`.
   - Android: run `scripts/android-check.sh`, optionally with a fully qualified test class.
     Never run `./gradlew clean` unless the user asks.
   - A task is done only when the relevant script prints `exit=0`. Quote its summary lines in your final message.
   - Every control a test touches gets a stable ID: `.accessibilityIdentifier(...)` in SwiftUI,
     `Modifier.testTag(...)` in Compose. Never locate elements by visible text alone.
   - Never edit snapshot references (`__Snapshots__/`, `src/test/snapshots/`) or weaken an existing
     assertion to make a test pass. Stop and report the failure instead.
   - New Swift files go inside an existing synchronized folder; do not edit `project.pbxproj` by hand.
   ```

5. **Zacommituj skrypty i uruchom je raz samodzielnie.** Skrypt, który pada na czystym checkoucie, uczy agenta, że można go ignorować. Uruchom oba, zajrzyj do `build/evidence/` i dopisz `build/` do `.gitignore`, jeśli jeszcze go tam nie ma.

**Dlaczego skrypty ukrywają większość logu**

Pełny log nadal leży na dysku w `build/evidence/`. Agent widzi około 40 linii: błędy i werdykt. Gdy potrzebuje więcej, sam przeszuka log `grep`em. Dzięki temu wolny build nie zjada okna kontekstu, w którym powinna się zmieścić twoja specyfikacja.

## Podłącz agenta do symulatora i emulatora

Testy dowodzą zachowania, które opisałeś. Do pracy eksploracyjnej (czy ekran wygląda dobrze, co się stanie po dotknięciu tutaj) agent musi widzieć urządzenie i nim sterować. Obsługują to dwa serwery MCP. Jeśli nigdy nie dodawałeś serwera MCP, przeczytaj najpierw [wprowadzenie do MCP](/pl/ecosystem/mcp/):

- **MobileBuildMCP** (wcześniej XcodeBuildMCP, utrzymywany przez Sentry) buduje, uruchamia i debuguje projekty iOS i macOS na symulatorach i urządzeniach. Wymaga macOS 14.5+ i Xcode 16+. Najczęściej używane narzędzie to `build_run_sim`: buduje schemat, instaluje aplikację na uruchomionym symulatorze, startuje ją i przechwytuje logi.
- **mobile-mcp** (Mobile Next) steruje symulatorami iOS, emulatorami Androida i fizycznymi urządzeniami przez jeden zestaw narzędzi: `mobile_list_elements_on_screen` do zrzutu drzewa dostępności, `mobile_take_screenshot`, `mobile_click_on_screen_at_coordinates`, `mobile_get_device_logs`, `mobile_get_crash` i inne. Wersja 1.0.5 udostępnia 32 narzędzia.

Popularność: 2026-09-26 MobileBuildMCP miał 6,4 tys. gwiazdek na GitHubie i pakiet npm `mobilebuildmcp` 2.7.1 (opublikowany 2026-09-23); 2026-09-28 mobile-mcp miał 7958 gwiazdek na GitHubie i pakiet npm `@mobilenext/mobile-mcp` 1.0.5 (opublikowany 2026-09-23). Źródła: repozytoria `getsentry/MobileBuildMCP` i `mobile-next/mobile-mcp` na GitHubie oraz rejestr npm.

**Claude Code**

    Dodaj serwery z terminala. Domyślny zakres `local` nie wpuszcza ich do sesji współpracowników, dopóki nie udostępnisz ich przez `-s project`:

    ```bash
    claude mcp add mobilebuild -- npx -y mobilebuildmcp@latest mcp
    claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
    ```

    Aplikacja desktopowa Claude Code na macOS ma też panel iOS Simulator (beta od lipca 2026), więc symulator widzisz obok sesji. Żeby agent nie ruszał referencji snapshotów, dodaj reguły deny do `.claude/settings.json`:

    ```json
    {
      "permissions": {
        "deny": [
          "Edit(**/__Snapshots__/**)",
          "Edit(**/src/test/snapshots/**)"
        ]
      }
    }
    ```

**Codex**

    Dodaj serwery przez `codex mcp add` (`--` oddziela komendę serwera):

    ```bash
    codex mcp add mobilebuild -- npx -y mobilebuildmcp@latest mcp
    codex mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
    ```

    Build na symulatorze potrafi trwać dłużej niż domyślny limit czasu narzędzia MCP. Dokumentacja klientów MobileBuildMCP każe użytkownikom Codeksa podnieść go osobno dla serwera w `~/.codex/config.toml`, bo Codex ignoruje `tool_timeout_sec` ustawione na najwyższym poziomie dla wywołań MCP:

    ```toml
    [mcp_servers.mobilebuild]
    command = "npx"
    args = ["-y", "mobilebuildmcp@2.7.1", "mcp"]   # pinned, like the committed configs
    tool_timeout_sec = 600
    ```

    Oficjalny marketplace wtyczek Codeksa zawiera też `build-ios-apps` (skille takie jak `ios-debugger-agent`, `swiftui-ui-patterns` i `swiftui-performance-audit`, z konfiguracją XcodeBuildMCP) oraz `test-android-apps` (skille `android-emulator-qa` i `android-performance`); sprawdzone w `openai/plugins` 2026-09-26. Zainstalujesz je z TUI: uruchom `/plugins` i wyszukaj po nazwie.

    Dwa szczegóły z plików wtyczek (w obu wersja 0.1.2): `build-ios-apps` uruchamia serwer pod starą nazwą pakietu, `xcodebuildmcp@latest`, z czterema włączonymi workflow (`simulator,ui-automation,debugging,logging`) i potrafi wyświetlić obraz symulatora w przeglądarce wbudowanej w Codeksa. Jeśli dodałeś też `mobilebuild` ręcznie, wyłącz jeden z nich, bo inaczej agent widzi każde narzędzie builda dwa razy.

**Cursor**

    Dodaj plik `.cursor/mcp.json` w zakresie projektu, żeby każdy, kto otworzy repozytorium, dostał te same serwery:

    ```json
    {
      "mcpServers": {
        "mobilebuild": {
          "command": "npx",
          "args": ["-y", "mobilebuildmcp@2.7.1", "mcp"]
        },
        "mobile-mcp": {
          "command": "npx",
          "args": ["-y", "@mobilenext/mobile-mcp@1.0.5"]
        }
      }
    }
    ```

    Wersje są przypięte, bo ten plik trafia do repozytorium: z `@latest` następna sesja każdej osoby w zespole po cichu uruchamia to, co opublikowano w nocy. Podbijaj wersje w pull requeście, jak każdą inną zależność.

    Agent Cursora uruchamia `scripts/ios-check.sh` i `scripts/android-check.sh` w swoim terminalu jak każdą inną komendę. Wskazówki mobilne specyficzne dla Cursora znajdziesz w artykule [programowanie mobilne w Cursorze](/pl/cursor-ide/build/mobile-dev/).

**Zanim podłączysz serwer urządzeń**

Oba serwery domyślnie wysyłają telemetrię: ustaw `MOBILEBUILDMCP_SENTRY_DISABLED=true` dla MobileBuildMCP (stary pakiet `xcodebuildmcp`, który wciąż uruchamia wtyczka Codeksa `build-ios-apps`, czyta `XCODEBUILDMCP_SENTRY_DISABLED`) i `MOBILEMCP_DISABLE_TELEMETRY=1` dla mobile-mcp, jeśli wymaga tego twoja polityka. mobile-mcp potrafi też sterować prawdziwym telefonem podłączonym przez USB, a więc agent może przeczytać wszystko, co jest na jego ekranie. Używaj urządzenia testowego z kontami testowymi, nigdy prywatnego telefonu. Narzędzia MobileBuildMCP do fizycznych urządzeń wymagają też skonfigurowanego podpisywania kodu w Xcode.

**Który wybrać.** MobileBuildMCP, gdy problemem jest sam build w Xcode (schematy, podpisywanie, makro w Swifcie, crash przy starcie). mobile-mcp, gdy problemem jest zachowanie na ekranie, na dowolnej platformie. Włączaj tylko serwer potrzebny w danej sesji: definicja każdego udostępnionego narzędzia zajmuje kontekst w każdej turze. mobile-mcp 1.0.5 udostępnia od razu wszystkie 32 narzędzia. MobileBuildMCP domyślnie wystawia tylko workflow `simulator`; poszerzaj go zmienną środowiskową `MOBILEBUILDMCP_ENABLED_WORKFLOWS` (na przykład `simulator,ui-automation,debugging,logging`) dopiero wtedy, gdy zadanie wymaga automatyzacji UI albo debuggera. W Claude Code wygląda to tak: `claude mcp add mobilebuild -e MOBILEBUILDMCP_ENABLED_WORKFLOWS=simulator,ui-automation -- npx -y mobilebuildmcp@latest mcp`. Wtyczka Codeksa `build-ios-apps` ustawia zamiast tego `XCODEBUILDMCP_ENABLED_WORKFLOWS` tylko dlatego, że uruchamia stary pakiet `xcodebuildmcp@latest`; `mobilebuildmcp` 2.7.1 ignoruje tę nazwę.

**Praca w Xcode zamiast w terminalu.** Dokumentacja klientów MobileBuildMCP (sprawdzona 2026-09-26) opisuje, jak Xcode 26.3 i nowsze wersje uruchamiają agentów Codex i Claude Code w **Xcode Settings > Intelligence**. Ci agenci startują z okrojonym `PATH`, więc serwer uruchamiany przez `npx` często się nie podnosi; dokumentacja opakowuje komendę w `/bin/zsh -lc` z Homebrew i nvm w `PATH`. Skrypty kontrolne z tej strony działają tak samo w obu miejscach.

## Jak zmieścić czas natywnego builda w pętli agenta

Wolna pętla zmienia zachowanie agenta: między buildami zbiera wiele edycji naraz, a błąd ma potem wiele możliwych przyczyn. Utrzymuj trzy pętle, każdą z własnym kosztem:

| Pętla | Co się uruchamia | Komenda | Kiedy agent ją odpala |
| --- | --- | --- | --- |
| Wewnętrzna | Testy jednostkowe zmienionego modułu (Swift Testing lub XCTest; JUnit) | `xcodebuild test ... -only-testing:AppTests/CartTests` · `./gradlew :feature:cart:testDebugUnitTest --tests '*CartViewModelTest'` | Po każdej edycji |
| Środkowa | Jedna klasa testów UI na przypiętym urządzeniu | `scripts/ios-check.sh AppUITests/CartUITests` · `scripts/android-check.sh com.example.cart.CartScreenTest` | Zanim ogłosi „gotowe” |
| Zewnętrzna | Wszystkie zestawy, weryfikacja snapshotów, obie platformy | Te same dwa skrypty bez argumentów, w CI | Przy każdym pull requeście |

Zasady, które utrzymują szybką pętlę wewnętrzną i środkową:

- **Nie czyść odruchowo.** Zapisz agentowi w pliku instrukcji, że `clean` jest zakazany, chyba że o to poprosisz. Większość odruchów „naprawmy to czystym buildem” bierze się z nieaktualnego DerivedData albo cache Gradle, a lista awarii poniżej podaje dla nich punktową naprawę.
- **Trzymaj urządzenia rozgrzane.** Oba skrypty uruchamiają urządzenie tylko wtedy, gdy nie działa. Zostaw symulator i emulator włączone przez całą sesję.
- **Włącz cache Gradle.** Dodaj `org.gradle.caching=true` i `org.gradle.configuration-cache=true` do `gradle.properties`. Configuration cache pomija ponowne wykonywanie skryptów builda, gdy nic się w nich nie zmieniło.
- **Rozdziel build i test na iOS przy powtórkach.** `xcodebuild build-for-testing`, a potem `xcodebuild test-without-building` ponawia niestabilny test bez rekompilacji. Używaj tego tylko do diagnozy: po zmianie kodu agent musi zbudować projekt od nowa.
- **Zmierz, zanim zaczniesz stroić.** `xcodebuild -showBuildTimingSummary` pokazuje, gdzie poszedł czas, a `./gradlew --profile` zapisuje lokalny raport HTML w `build/reports/profile/`. Poproś agenta, żeby przeczytał raport i zaproponował jedną zmianę, a potem zmierz ponownie.

**Prompt do skopiowania: znajdź najwolniejszą część builda**

```text
Run `./gradlew :app:assembleDebug --profile` twice (the second run shows the incremental cost),
then read the newest report under build/reports/profile/. List the five slowest tasks with their
durations, explain why each one runs on an incremental build, and propose ONE change to
gradle.properties or a build script that removes the biggest cost. Do not apply it yet. Show me
the change and the command you will use to prove it helped.
```

## Receptura: ekran w SwiftUI z dowodem z testów UI

Poniższy prompt najpierw prosi o zachowanie zapisane jako testy, a metą czyni kod wyjścia skryptu.

**Prompt do skopiowania: ekran ustawień w SwiftUI z dowodem**

```text
Build a SwiftUI SettingsView with a "Daily reminder" Toggle and a DatePicker that is only enabled
when the toggle is on. The state lives in an @Observable SettingsModel persisted to UserDefaults.

Work in this order:
1. Write Swift Testing tests (import Testing, @Test, #expect) for SettingsModel: default is off,
   toggling persists, the time survives a relaunch (new model instance reading the same defaults suite).
2. Write an XCUITest class AppUITests/SettingsUITests that launches the app with the launch argument
   "-uiTesting", opens Settings, turns the toggle on, and asserts the DatePicker is enabled.
   Attach a screenshot after each step with XCTAttachment and lifetime .keepAlways.
3. Implement until `scripts/ios-check.sh AppUITests/SettingsUITests` prints exit=0, then run
   `scripts/ios-check.sh` with no argument.
Put new files in the existing synchronized folders. Give every control an accessibilityIdentifier.
Finish with the script's summary lines and the list of tests you added.
```

Zrzuty ekranu trafiają do `build/evidence/ios/tests.xcresult`, obok testu, który je wykonał. Kod załącznika, który agent powinien wygenerować, wygląda tak:

```swift
let app = XCUIApplication()

func snap(_ name: String) {
    let shot = XCTAttachment(screenshot: app.screenshot())
    shot.name = name
    shot.lifetime = .keepAlways   // keep it even when the test passes
    add(shot)
}

func testEnablingReminderEnablesTimePicker() {
    app.launchArguments = ["-uiTesting"]
    app.launch()
    app.buttons["settings.open"].tap()
    snap("1-settings-open")
    app.switches["settings.reminderToggle"].tap()
    snap("2-reminder-on")
    XCTAssertTrue(app.datePickers["settings.reminderTime"].isEnabled)
    snap("3-time-picker-enabled")
}
```

Sprawdź jedną rzecz, którą agent często psuje: argument startowy `-uiTesting` musi zmieniać zachowanie aplikacji (zestaw `UserDefaults` w pamięci, brak onboardingu). Jeśli nic w aplikacji go nie czyta, test UI zależy od stanu zostawionego przez poprzedni przebieg i będzie niestabilny.

## Receptura: ekran w Jetpack Compose z dowodem z testów UI

**Prompt do skopiowania: ekran koszyka w Compose z dowodem**

```text
Build a Jetpack Compose CartScreen backed by a CartViewModel (StateFlow<CartUiState>) with three
states: Loading, Empty, and Items(list, total). Quantity steppers update the total immediately.

Work in this order:
1. JUnit tests for CartViewModel with a fake repository: empty cart gives Empty, incrementing a line
   updates the total, a repository error gives an error state with a retry action.
2. A Compose UI test com.example.cart.CartScreenTest using createAndroidComposeRule<MainActivity>():
   find nodes by Modifier.testTag, tap "+" on the first line, assert the total text changes.
3. Implement until `scripts/android-check.sh com.example.cart.CartScreenTest` prints exit=0,
   then run `scripts/android-check.sh` with no argument.
Do not run ./gradlew clean. Finish with the script's summary lines and the tests you added.
```

Poprawny test w Compose szuka węzłów po tagu, nie po tekście, więc zmiana copy go nie psuje:

```kotlin
@get:Rule val composeRule = createAndroidComposeRule<MainActivity>()

@Test
fun incrementUpdatesTotal() {
    composeRule.onNodeWithTag("cart.line.0.increment").performClick()
    composeRule.onNodeWithTag("cart.total").assertTextEquals("Total: 24.00")
}
```

Dowód wizualny na Androidzie bez emulatora da biblioteka testów zrzutów ekranu, na przykład Paparazzi: `./gradlew :app:recordPaparazziDebug` nagrywa obrazy referencyjne, a `./gradlew :app:verifyPaparazziDebug` pada, gdy renderowanie się zmieni. Na iOS tę samą rolę pełni `swift-snapshot-testing` z `assertSnapshot(of: view, as: .image)`. Obie biblioteki nagrywają referencje przy pierwszym uruchomieniu, więc te referencje przejrzyj i zacommituj sam.

## Receptura: odtwórz crasha, którego agent nie widzi

Raport crasha ze stack trace’em to specyfikacja czerwonego testu. Przekaż go agentowi z podłączonym serwerem urządzeń:

**Prompt do skopiowania: zamień crasha w czerwony test**

```text
Here is a crash from our Android beta (stack trace below). Using the mobile-mcp tools:
1. Launch the debug build on the running emulator, follow the steps in the report, and capture
   mobile_get_device_logs and a screenshot when it crashes.
2. Write the smallest instrumented or unit test that reproduces the crash. Run it with
   scripts/android-check.sh and show me it FAILS for the same reason as the report.
3. Only then fix the code, rerun the script until exit=0, and explain the root cause in two sentences.
Do not change or delete any existing test.

<paste the stack trace here>
```

Kolejność ma znaczenie. Test, który przed poprawką był czerwony, a po niej jest zielony, to dowód. Poprawka bez wcześniejszego czerwonego testu to zgadywanie, które akurat się skompilowało.

## Jak zweryfikować natywną pracę agenta bez czytania każdej linii

Skrypty zamieniają każdą zmianę w ten sam zestaw artefaktów, a przegląd zaczyna się od tego zestawu, nie od diffa:

| Dowód | Gdzie leży | Co sprawdza recenzent |
| --- | --- | --- |
| Werdykt testów | Ostatnie linie wyjścia skryptu, `summary.json`, JUnit XML w `androidTest-results/` | `exit=0` na obu platformach; liczba testów rośnie, nigdy nie maleje |
| Zrzuty ekranu UI | Załączniki w `tests.xcresult` (otwierane w Xcode), obrazy Paparazzi lub snapshot-testing | Ekrany zgadzają się ze specyfikacją; różnice w snapshotach są zamierzone |
| Logi z działania | `xcodebuild.log`, `logcat.txt` | Brak nowych crashy, ANR-ów i zalewu błędów podczas testów UI |
| Zmiany w testach | Pliki testów w diffie | Nowe testy sprawdzają kryteria akceptacji; żadna asercja nie została osłabiona, żaden snapshot nie został przenagrany bez powodu |

Trzy zasady sprawiają, że można temu ufać:

1. **CI uruchamia te same skrypty.** Zielony wynik w sesji agenta to deklaracja; ten sam skrypt w CI na czystym runnerze macOS to dowód. Trzymaj skrypty w repozytorium, żeby te dwa przebiegi nie mogły się rozjechać.
2. **Agent nie może edytować wyroczni.** Referencje snapshotów i testy kodujące kryteria akceptacji są chronione, tak jak opisuje to artykuł o [ochronie wyroczni testowej](/pl/workflows/test/protect-the-oracle/). Claude Code dostaje reguły deny dla ścieżek (zakładka Claude Code wyżej). W Codeksie i Cursorze ta strona opiera się zamiast tego na zabezpieczeniu niezależnym od narzędzia, które przy okazji wspiera też Claude Code: CODEOWNERS na katalogach z referencjami oraz krok CI, który pada, gdy zmieniają się one bez etykiety.

   ```text
   # .github/CODEOWNERS
   **/__Snapshots__/        @your-org/mobile-leads
   **/src/test/snapshots/   @your-org/mobile-leads
   ```

   ```yaml
   # CI job step (check out with fetch-depth: 0 so origin/main is available)
   - name: Block unlabelled snapshot changes
     if: ${{ !contains(github.event.pull_request.labels.*.name, 'snapshot-update') }}
     run: |
       if git diff --name-only origin/main... | grep -E '__Snapshots__/|src/test/snapshots/'; then
         echo "Snapshot references changed without the snapshot-update label"; exit 1
       fi
   ```
3. **Konkretna osoba zatwierdza dowody.** Deweloper, który zlecił zadanie, przegląda zestaw dowodów i diff testów. Diff kodu człowiek czyta w całości tylko tam, gdzie wymaga tego ryzyko: podpisywanie, entitlements, płatności i wszystko, co dotyka uprawnień w `Info.plist` lub `AndroidManifest.xml`.

Kontrakt pull requesta dla tego zestawu opisuje artykuł o [pakiecie dowodów](/pl/workflows/ship/evidence-bundle/), a uzasadnienie przeglądu dowodów zamiast diffów — artykuł [czytanie dowodów zamiast kodu](/pl/ladder/evidence-not-diffs/).

## Kiedy natywna pętla agenta się psuje

**Typowe awarie i wyjście z nich**

**Nowy plik Swift kompiluje się w edytorze, ale nie w buildzie.** Plik nie należy do żadnego targetu. Zamień grupę na synchronizowany folder w Xcode 16 lub nowszym (prawy przycisk na grupie, **Convert to Folder**), żeby każdy plik w środku trafiał do targetu, i powiedz agentowi, gdzie mają lądować nowe pliki. Nie pozwalaj mu ręcznie edytować `project.pbxproj`; konflikt przy merge’u w tym pliku drogo się rozplątuje.

**„Unable to find a destination matching the provided destination specifier.”** Przypięta nazwa symulatora nie istnieje w tej wersji Xcode. Uruchom `xcrun simctl list devices available`, popraw `SIM` w skrypcie i zacommituj zmianę. Nie pozwól agentowi samemu wybierać „dowolnego iPhone’a”, bo to odpina urządzenie.

**Build w sandboksie pada z błędami uprawnień.** Xcode domyślnie pisze do `~/Library/Developer/Xcode/DerivedData`, czyli poza projekt. Właśnie dlatego skrypty przekazują `-derivedDataPath build/DerivedData`; sprawdź, czy agent nie woła `xcodebuild` bezpośrednio.

**Emulator w CI nigdy nie kończy startu.** Bezgłowe runnery często nie mają akceleracji sprzętowej. Sprawdź log emulatora w `build/evidence/android/emulator.log` i użyj runnera z włączonym KVM albo Gradle Managed Devices zamiast ręcznie uruchamianego emulatora.

**Agent przenagrywa snapshoty, żeby test przeszedł.** Ustawienie `record: .all` w swift-snapshot-testing albo uruchomienie `recordPaparazziDebug` zmienia każdą regresję wizualną w zielony wynik. Zablokuj edycję katalogów z referencjami i traktuj każdy zmieniony obraz referencyjny w pull requeście jako zmianę, która wymaga uzasadnienia.

**Build pada z błędami nieaktualnych modułów albo cache.** Błędy typu moduł skompilowany innym kompilatorem, brakujący prekompilowany nagłówek albo niezgodność configuration cache w Gradle biorą się z cache, a nie z twojego kodu. Na iOS usuń tylko `build/DerivedData/ModuleCache.noindex` (albo cały `build/DerivedData`, którym zarządzają skrypty). Na Androidzie uruchom `./gradlew --stop` i usuń `.gradle/configuration-cache`. Potem uruchom ponownie skrypt sprawdzający. Nie rób pełnego `clean`: wyrzuca każdy rozgrzany cache i spowalnia kilka następnych iteracji agenta.

**Serwer MCP u kolegi zachowuje się inaczej niż u ciebie.** Jego sesja pobrała w nocy nowsze wydanie `@latest`. Przypnij wersję serwera w każdej konfiguracji trzymanej w repozytorium (`.cursor/mcp.json` albo `.mcp.json`, który zapisuje `claude mcp add -s project`), tej samej wersji użyj w `~/.codex/config.toml` i aktualizuj ją świadomie.

**Wywołania MCP przekraczają limit czasu podczas builda.** W Codeksie ustaw `tool_timeout_sec` we własnym bloku serwera `[mcp_servers.<name>]`. W każdym narzędziu pełny build zostaw skryptowi, a serwera MCP używaj do uruchamiania i oglądania aplikacji.

**Kontekst zapycha się logiem builda.** Agent woła `xcodebuild` albo `./gradlew` bezpośrednio zamiast skryptów. Odeślij go do reguły w pliku instrukcji i poproś, żeby przeszukał `grep`em zapisany log pod kątem potrzebnego błędu.

## Model i poziom wysiłku (`effort`) przy pracy natywnej

Zacznij od domyślnego modelu swojego narzędzia i podnieś poziom `effort`, zanim zmienisz model; aktualne ustawienia domyślne i ceny są w [przeglądzie modeli](/pl/ecosystem/models/). Zadania natywne częściej ogranicza informacja zwrotna z builda niż model, więc najpierw napraw pętlę.

## Co dalej z natywnymi agentami na iOS i Androida

- [Wzorce testowania aplikacji mobilnych](/pl/workflows/test/mobile-testing/) — Macierze urządzeń, przepływy Detox i Maestro oraz testy gestów i trybu offline na obu platformach.
- [Pakiet dowodów](/pl/workflows/ship/evidence-bundle/) — Kontrakt pull requesta, który zamienia wyjście skryptów w dowód gotowy do przeglądu.
- [Serwery MCP narzędzi deweloperskich frameworków](/pl/ecosystem/mcp/framework-devtools-mcp/) — MobileBuildMCP obok innych serwerów, które wprowadzają działającą aplikację do pętli agenta.
- [Wzorce React Native](/pl/cookbook/mobile-development/react-native/) — Alternatywa wieloplatformowa: Expo, FlashList i EAS Build.
- [Wzorce Flutter](/pl/cookbook/mobile-development/flutter/) — Riverpod, go_router i testy widgetów, gdy jedna baza kodu w Darcie obsługuje obie platformy.
- [Przegląd programowania mobilnego](/pl/cookbook/mobile-development/) — Wszystkie receptury mobilne i to, do jakiego stosu pasuje każda z nich.
