Development and testing¶
uv sync --group dev
uv run pytest # tests
uv run mypy # strict type check of the package and of tests/typing
uv run pyright # the checker behind VS Code's Pylance
uv run ruff check
Releasing¶
Releases go to PyPI from GitHub Actions (.github/workflows/release.yml), with
Trusted Publishing: no API token.
- Set
__version__insrc/pyios_firebase/__init__.py, and merge tomain. - Tag the merge and push the tag:
Or on GitHub: Releases > Draft a new release, type v0.2.0 in Choose
a tag (Create new tag on publish), target main, and Publish
release. Publishing creates the tag.
The tag runs the checks, builds the sdist and the wheel, checks that the tag
matches __version__, publishes to PyPI, and attaches the files to the
GitHub Release (it creates the release for a pushed tag). Run workflow on the Release workflow publishes to TestPyPI
instead, as a dry run.
End-to-end tests on the iOS Simulator¶
This builds a small Kivy app (e2e/ios/) with the wheel from your checkout and
the real Firebase iOS SDK, runs it in the iOS Simulator against the local
Firestore, Auth, Functions, Storage and Realtime Database emulators, and exits
non-zero if any test fails. The app is launched twice: the first launch runs
the suites and then crashes on purpose, and the second checks that Crashlytics
recorded the crash.
- Firestore: every value type, writes and field values, merges, queries and cursors, OR/AND filters, collection groups, aggregates, listeners and their change types, batches, transactions, and read sources.
- Auth: email/password, errors and their codes, state and ID token listeners, anonymous upgrade, linking and unlinking a provider, custom tokens and claims, phone sign-in, profile and tokens, re-authentication, password change and account deletion, password reset, email verification, email link sign-in, SMS multi-factor enrollment and sign-in, passing state in email links, the shared keychain, OAuth providers, and the Facebook SDK bridge. The emails and SMS codes are read from the Auth emulator's REST API. TOTP is skipped: the Auth emulator supports only SMS second factors.
- Functions: JSON round trip,
HttpsErrorcodes and details, unexpected errors, unknown functions, timeouts, the Auth context, regions, calls by URL, App Check tokens (normal and limited-use), and non-JSON data. The functions are Python Cloud Functions (firebase_functions) ine2e/functions/main.py. - Storage: references, upload with metadata, metadata update and delete, download URL, download to memory and to a file, file upload, listing and paging, upload progress, cancel, and errors.
- Remote Config (no emulator exists): plist defaults, values and their sources, merged defaults, settings, a fetch failing cleanly offline, custom signals and the update listener.
- App Check: a Python custom provider serving the whole app, tokens and
limited-use tokens, the token listener, settings, and the debug token from
FIRAAppCheckDebugToken. - Realtime Database: value types, listeners for values and child events (with
previous keys), sorting and filtering, multi-path updates, server timestamps
and increments, transactions (committed, aborted, raising), priorities and the
export format, security rules errors, Python errors instead of aborts,
.info/connectedandon_disconnect. - Analytics (no emulator exists): events, e-commerce items, screen views, user properties, consent with the SDK's own constants, IDs, and name checks.
- Crashlytics: logs, keys, non-fatal Python exceptions with their frames, the excepthook, and a real crash found again on the next launch, with its unsent report.
- Messaging: settings, the APNs token, topic checks, delivery analytics, the
token call, provisional notification permission, and a notification pushed
to the Simulator (
xcrun simctl push) arriving in the foreground handler. - Performance Monitoring (no emulator exists): traces with metrics and
attributes, a Python request measured with
HTTPMetric, inactive traces while collection is off, and name checks.
It needs Xcode with an iOS simulator, uv,
firebase-tools and Java 21+ for the emulators. The first run creates a Python
3.13 venv for the e2e functions with uv. It
uses the offline demo-pyios-firebase project: no Firebase account or
credentials. E2E_DEVICE picks the simulator (default iPhone 17). The first
build takes a few minutes; results, the app log and a screenshot land in
e2e/ios/build/e2e/.
Unit tests run fake Firebase objects; the end-to-end suite is what catches
mismatches with the real SDK. It found bugs the unit tests could not: Objective-C
getters Rubicon exposes as methods (is_from_cache, NSDate values), TLS left on
for the Firestore emulator, and the SDK stopping the app for a missing URL scheme.
tests/test_docs.py fails if a public function or method has a parameter its
Args: docs do not describe (or describes one it does not have).
tests/typing/check_public_api.py is type-checked, never run: it uses the
public API the way an app does, asserts what the checker infers, and lists
mistakes the types must keep catching.
The tests run on macOS: Rubicon works there, and fake Firebase objects call the real callback blocks. They check callbacks, errors, block lifetimes, transactions, and value conversion. They do not replace testing on a device with the real Firebase SDK.