firebase-ios-sdk/Firestore/README.md

Usage

Xcode

• Install prerequisite software

• Set up a workspace via CocoaPods (this opens Xcode):

  $ cd Firestore/Example
  $ pod update
  $ open Firestore.xcworkspace
  

• Select the Firestore_Tests_iOS scheme

• ⌘-u to build and run the unit tests

Command-line builds

You can also build from the command-line, though this requires a slightly different setup:

PLATFORM=iOS pod update --project-directory=Firestore/Example
scripts/build.sh Firestore iOS

Note:

• PLATFORM here is specifying an environment variable that's active for the pod update invocation.
• You can also use macOS or tvOS in place of iOS above.
• This will modify the Xcode project files; you'll need to revert these changes to create a PR.

The issue that requires this workaround is that Firestore's Podfile contains multiple platforms, and ever since Xcode 10.2, CocoaPods generates Xcode projects that are break by default when built by the xcodebuild command-line tool. There's a workaround possible that involves disabling Xcode's default mechanism of finding implicit dependencies, but this is something we'd have to disable Firebase-wide and there hasn't been an appetite to do this.

Swift package manager

Firestore also supports building with Swift Package Manager. To build this way use:

scripts/build.sh Firestore iOS spm

This is rarely necessary for primary development and is done automatically by CI.

For a detailed explanation of the Firestore target hierarchy in the Package.swift manifest, see FirestoreSPM.md.

Improving the debugger experience

You can install a set of type formatters to improve the presentation of Firestore internals in LLDB and Xcode. Add the following to your ~/.lldbinit file:

command script import ~/path/to/firebase-ios-sdk/scripts/lldb/firestore.py

(substitute the location of your checkout of the firebase-ios-sdk.)

Testing

Running Integration Tests

Prefer running the integration tests against the Firestore Emulator. This is much faster than running against production and does not require you to configure a Firestore-enabled project.

• In a new terminal, run scripts/run_firestore_emulator.sh and leave it running.
• In Xcode select the Firestore_IntegrationTests_iOS scheme (or macOS or tvOS).
• ⌘-u to build and run the integration tests.

The command-line build script runs integration tests by default and will start and stop an emulator for you.

Running Integration Tests - against production

Occasionally it's useful to run integration tests against a production account.

• Set up a GoogleServices-Info.plist file in Firestore/Example/App.
• Ensure your Firestore database has open rules (the integration tests do not authenticate).
• In Xcode select the Firestore_IntegrationTests_iOS scheme
• ⌘-u to build and run the integration tests

If you want to switch back to running integration tests against the emulator:

• Ensure that GoogleServices-Info.plist is in its default state (git checkout Firestore/Example/App/GoogleServices-Info.plist).

Testing composite index query against production

Setting Up the Environment:

1. Set up a GoogleServices-Info.plist file in Firestore/Example/App.
2. If not already logged in, authenticate with your Google Cloud Platform (GCP) account using gcloud auth application-default login. You can check your logged-in accounts by running gcloud auth list.

3. Navigate to the Firestore directory, create composite indexes by running:

   terraform init
   terraform apply -var="project_id=<your-project-id>" -auto-approve
   

4. Run integration tests as guided in "Running Integration Tests - against production".

Note: If the index creation encounters issues, such as concurrent operations, consider running the index creation process again. Error messages indicating that indexes have already been created can be safely disregarded.

Adding new composite index query tests

1. To create a new composite index for local development, click on the provided link in the test error message, which will direct you to the Firebase Console.
2. Add the newly created composite index to the firestore_index_config.tf file. The "name" field is not required to be explicitly added to the file, as the index creation will auto complete it on behalf.

Other tasks

Building Protos

Typically you should not need to worrying about regenerating the C++ files from the .proto files. If you do, see instructions at Protos/README.md.