How-To

How to Test App Upgrades and Data Migration on iOS and Android

A fresh install never meets the data your users already have. Test the iOS and Android upgrade path, where migrations break, on every release candidate.

Adithya Aggarwal

CTO & Co-founder at Pie

11 min read Posted Oct 16, 2026

A fresh install starts from nothing. Your users never do. They update, and the new build opens a database, a keychain, and a set of preferences the old build wrote. An install test never walks that path, so it never fails on it.

Miss one migration and the update either crashes on launch or quietly wipes a user’s data. Here is how to test that path before your users do.

Why Upgrades Break When Fresh Installs Pass

An upgrade runs new code against old data, and a fresh install never does. On an update from the App Store or Play Store, the OS keeps the app’s stored data and swaps in the new binary. Picture replacing an engine while the car keeps its mileage and the luggage in the trunk. The new binary has to read everything the old one wrote. Each assumption about that data’s shape is a place to break.

Install tests miss this by construction. They provision a clean device. The app boots with no prior state, and every read returns what the current code wrote. The upgrade path sits underneath every scenario in a mobile app testing strategy, and install-only suites never touch it.

Adding a column is a one-line diff. The migration for the rows that already exist is a second change that nothing in the first diff asks for. A missing migration costs nothing to ship and stays invisible until a real user updates.

TLDR: An install test checks new code on new data. An upgrade test checks new code on old data.

Five Places an Upgrade Loses Data

User data on a phone sits in five storage layers, and each one migrates on its own rules. One can break while the other four pass. Assert all five.

Four details change what you assert:

• Keychain: On iOS, Keychain items have survived an app delete in practice, so a login can outlast a delete-and-reinstall. Apple’s developer forums call that an undocumented implementation detail. A reinstall test can hide the logout bugs that an in-place upgrade exposes.
• File paths: An iOS app’s container gets a new absolute path when the app updates. A full path the old build saved in its database then points at nothing. Apple’s technote on testing iOS app updates says to store paths relative to the container instead.
• Server-driven state: Subscription entitlements go wrong on update when the new client reads an old receipt shape. The guide to testing in-app subscriptions covers the entitlement side.
• Permissions: A grant given at onboarding has to survive the update, and Android auto-resets permissions when an app targeting Android 11 or higher goes unused for a few months. Test app permissions across the upgrade as well as on first run.

How to Test Database Schema Migration

Test a schema migration twice: in isolation, to prove each step works, then end to end, to prove the old build’s real data survives. The local database is where an upgrade does the most visible damage, because a missing migration does not degrade gracefully. It crashes the app on launch or deletes the user’s records. In Room, one configuration flag decides which.

Test Room Migrations on Android

Room is Android’s Jetpack library for local databases, an abstraction layer over SQLite. It resolves a chain of Migration objects between schema version numbers, and each Migration moves the schema from one version to the next. The code below is Room 2.x. Room 3 makes migrate a suspend function over a SQLiteConnection, and the rules below hold in both:

val MIGRATION_3_4 = object : Migration(3, 4) {
  override fun migrate(db: SupportSQLiteDatabase) {
    db.execSQL("ALTER TABLE pets ADD COLUMN collar_id TEXT")
  }
}

Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
    .addMigrations(MIGRATION_2_3, MIGRATION_3_4) // every step must be registered
    .build()

Room’s documentation is explicit about a missing step. If it “can’t find a migration path to upgrade an existing database on a device to the current version, an IllegalStateException occurs.” The app crashes on launch.

The tempting fix is fallbackToDestructiveMigration(). Android’s docs warn what it does: Room “permanently deletes all data from the tables in the user’s database when it attempts to perform a migration and there’s no defined migration path.” So the two failure modes are a launch crash or a silent, total data wipe, and a fresh-install test shows neither.

Prove each step in isolation first with Room’s MigrationTestHelper, which the same docs cover under “Test migrations.” The helper creates a database at an old schema version, and you insert rows with plain SQL because DAOs expect the latest schema. Then runMigrationsAndValidate applies your migrations and checks the result against the new schema. It checks the schema only. Asserting the data is on you.

Test Core Data Migrations on iOS

Core Data is Apple’s framework for persisting an app’s data on the device. Its lightweight migration infers the mapping for obvious changes such as adding, removing, or renaming an attribute. A change outside that list, such as merging entity hierarchies, needs a custom mapping model you ship yourself. An attribute type change is not on Apple’s list either. Without a mapping, loading the store fails with a Core Data error, and the app launches into an error state instead of the user’s data.

To test it, keep a store file written by the old model version in your test bundle, copy it to a temporary path, and open it with the new model. The test passes only if the store loads and the old rows read back.

Make one of those store files large. Apple lists a synchronous lightweight migration on a large Core Data store among the causes of watchdog terminations, where iOS ends an app whose main thread stays blocked too long. A store with a handful of test rows never gets near that limit.

The two platforms diverge enough that one test plan will not cover both. Build the migration matrix per platform.

When a Migration Needs a Table Rebuild

Room sits on SQLite, as does Core Data when it uses its SQLite store. SQLite supports a limited subset of ALTER TABLE, and a column type change is outside it. The migration has to create a new table, copy the rows across, drop the old table, and rename the new one. That copy step is where a hand-written migration can drop rows. Seed every table before you migrate.

On older Android, dropping a column needs the same rebuild. DROP COLUMN arrived in SQLite 3.35. Android’s platform SQLite is 3.32 or older through API 33. A Room migration on the framework driver that drops a column can pass on an API 35 emulator and fail on an Android 13 phone. BundledSQLiteDriver avoids that by compiling in its own SQLite.

TLDR: Prove each migration step in isolation. Then upgrade the last production build and check the data survived.

How to Run an Upgrade Test in Four Steps

Run it in four steps: install the old build, generate real state, upgrade in place, then assert everything survived. Everything rides on step three.

1. Install the last production build. Not the release candidate. The test has to start from the build your users run today.
2. Generate real state. Log in, create records, change settings, download something for offline use, start a subscription if you sell one. The closer the state is to a user’s, the more the test is worth. An empty database migrates fine, and a full one is where bugs live.
3. Upgrade over the top. Install the release candidate without uninstalling. The OS keeps the existing files and runs the new binary against them, as a store update does.
4. Assert survival, layer by layer. Walk the five layers from the table above. Is the session valid, are the records all present, did settings hold, does cached content load, is the subscription active? Any value that comes back empty or default is a defect.

Upgrade testing is regression work. Every schema change or storage refactor reopens the risk. The upgrade path belongs in your mobile regression testing suite, run against every release candidate.

Which Version Jumps to Test

Test the version jumps your users make, not every possible pair. A user does not always update from the previous version. Apple’s update-testing technote notes that the App Store installs the latest version without running the intermediate updates. Someone who skipped several releases gets every schema change between their version and yours applied in one launch, and a missing step hides in that longer chain. Testing only consecutive versions never walks it.

Build the matrix from your own install analytics. Cover at least these three jumps.

• Previous release to current: The most common path and your baseline. If this breaks, the largest group of updating users hits it.
• Oldest supported version to current: The longest migration chain you have to support, set by the oldest build that still holds a meaningful share of installs.
• Across a major boundary: Releases that changed schema, storage format, or auth accumulate migration debt, so an upgrade spanning one is higher risk than its version distance suggests.

You cannot test every historical version against every newer one, and you should not try. The combinatorics explode and most pairs represent nobody. Weight the matrix by where your users sit, as you would a device matrix.

How to Automate Upgrade Testing in CI

Automate upgrade testing by storing the previous production artifact next to the release candidate, then scripting an install-seed-upgrade-assert sequence in your pipeline. A manual upgrade test runs occasionally, while the schema changes that cause upgrade bugs land whenever a feature needs a new field. The pipeline has to keep the old build and drive the upgrade itself.

On Android the core of it is two installs and a relaunch. The -r flag reinstalls an existing app and keeps its data, which makes the second install an in-place upgrade.

# 1. Install the current production build, then seed real state
adb install -r app-prod.apk
# run a script that logs in and creates records...

# 2. Upgrade in place with the release candidate (-r keeps existing data)
adb install -r app-rc.apk

# 3. Relaunch and let the regression suite assert the data survived
adb shell am start -n com.yourcompany.app/.MainActivity

On iOS the shape is the same. The build has to be a simulator build.

# 1. Install the prior simulator build, then seed real state
xcrun simctl install booted App-prod.app
# run a script that logs in and creates records...

# 2. Install the candidate over it, without erasing the device
xcrun simctl install booted App-rc.app

# 3. Relaunch and run your assertions
xcrun simctl launch booted com.yourcompany.app

Run the sequence by hand once and confirm the seeded data survives the second install before you wire it into CI. Google also documents a way to exercise the store’s own in-app update flow through internal app sharing, which is worth adding once the data-layer test is solid. Two cautions apply either way:

• Seed through the app: Create the state through the app’s own flows instead of pushing a fixture database onto the device. A hand-built fixture can encode a schema your old version never produced, and then you are testing a migration from a state that never existed.
• Expect flake: Upgrade tests inherit every source of mobile E2E flakiness plus a stateful setup phase. Keep the seeding hermetic and synchronize assertions on app state, the same discipline that stabilizes the rest of your mobile test automation.

TLDR: Keep last production’s artifact. Install it, seed state, install the candidate over it, then assert.

Where Pie Fits in an Upgrade Test

The install-over-install steps are a short script. What decays is the suite that checks the result: login, saved records, settings, each one rewritten whenever the UI moves. That upkeep is an easy reason to drop upgrade testing from the release checklist.

Pie, an autonomous QA platform for native iOS and Android apps, takes the suite. Upload the build your pipeline produces, an .apk for Android or a simulator .app for iOS, through the portal or a GitHub Action. Pie’s agents explore the app and generate tests from the flows they find. The tests run on an Android Emulator or an iOS Simulator, so the iOS candidate has to be a simulator build, and Pie does not accept a device .ipa.

After that first pass, the upkeep looks like this:

• Later builds: With auto-run on build turned on, each build you upload runs against that suite, and you can start a run on demand.
• UI changes: When a redesign moves a recognizable button, Pie can still find it by context, position, and function, so the move may need no locator repair. If the intended behavior changes, you edit the step.
• Regressions: Pie Loop can prepare a proposed fix as a pull request for your team to review, when repo access is connected and fix settings allow it.

Upgrade in Place, Every Release

An install test proves the app works for someone who has never opened it. Everyone else meets new code on top of old data the day they update.

What works is small. Upgrade in place, assert all five storage layers, weight the version jumps by your analytics, and run it on every release candidate.

Pie generates the regression flows you assert against, and its tests can find a moved or renamed button without a selector fix. Ship the upgrade test with your next migration.

Adithya Aggarwal

CTO & Co-founder at Pie

Eight years building search and delivery systems at Amazon. The kind of scale where flaky tests block billion-dollar releases. Now CTO at Pie, building AI agents that adapt when your UI changes. LinkedIn →