DocumentationPyPI

Device Testing

Manual checklist for testing a patched IPA on a real iPhone via AltStore Classic.

forge patch produces a signed, standard-structure .ipa. Everything up to that point is covered by the automated test suite (pytest tests/). What is not and cannot be automated in this environment is confirming AltStore Classic itself accepts, installs, launches, and refreshes the result on a real iPhone. This is a manual procedure to run by hand.

Prerequisites

  • AltServer running on the same Mac/PC used to sign the IPA, paired with your iPhone over USB or Wi-Fi (see AltStore Classic's own setup docs).
  • A real (not synthetic) .ipa to patch, or the fixtures/synthetic_app.ipa fixture for a structural-only smoke test (it will install and its process will launch, but it has no UI).
  • A matching .mobileprovision and signing identity for your Apple ID's team, produced the normal way through AltServer's own account/profile management (see Signing identity & profile).

Checklist

Patch

forge patch --ipa <input> --patches <patches.yaml> --identity <identity> --profile <profile> --output patched.ipa

Install

In AltStore's "My Apps" tab, use "+" and select patched.ipa.

Expected: install completes without AltStore error 1007 ("not a standard .ipa").

Launch

Tap the installed app icon on the home screen.

Expected: app launches without an "Unable to Install" / "Untrusted Developer" prompt (trust the developer certificate in Settings if iOS prompts for it on first launch of a personal-team build).

Confirm the patch took effect

Check whatever the patch definition changed (a swapped resource, a binary behavior change, etc).

Force a refresh

In AltStore's "My Apps", pull to refresh (or wait for AltServer's background refresh). Confirm the app's expiry date extends and the app still launches afterward without re-signing errors.

Expiry note

A free Apple ID sideload expires after 7 days and AltStore currently limits free accounts to 3 active sideloaded apps and 10 App IDs per rolling 7-day window — if refresh silently fails, check those limits before assuming the patcher produced a bad IPA.

If any step fails

Capture forge patch --verbose output (the manifest) and the on-device error text — both are needed to tell a patcher bug apart from an AltStore/account-limit issue.

Usage

Signing identity & profile setup

Edit on GitHub

Troubleshooting

Every ipa-forge error message mapped to its cause and fix.

Architecture

How the ipa-forge engine works: the 17-stage pipeline, hard constraints, component map, and two real bugs found empirically.

On this page

PrerequisitesChecklistPatchInstallLaunchConfirm the patch took effectForce a refreshExpiry noteRelated