From 9548af388788eb90593ce67cd69d3ee0bf6dba33 Mon Sep 17 00:00:00 2001 From: Jonathan Edey Date: Thu, 16 Nov 2023 11:00:33 -0500 Subject: [PATCH] mirror Tech Writer review changes --- CONTRIBUTING.md | 83 +++++++++++++++++++++++++++---------------------- 1 file changed, 45 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1eaaaab62..421327b5c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -163,19 +163,21 @@ pytest --cov=firebase_admin --cov=tests ### Integration Testing -A suite of integration tests are available under the `integration/` directory. These tests -are designed to run against an actual Firebase project. If you do not already have one -suitable for running the tests against, you can create a new project in the +Integration tests are executed against a real life Firebase project. If you do not already +have one suitable for running the tests against, you can create a new project in the [Firebase Console](https://console.firebase.google.com) following the setup guide below. -Otherwise you can obtain the following credentials from your current project: +If you already have a Firebase project, you'll need to obtain credentials to communicate and +authorize access to your Firebase project: -1. Service account certificate: This can be downloaded as a JSON file from the -**'Settings > Service Accounts'** tab of the Firebase console when you click the -**'Generate new private key'** button. Copy the file into the repo so it's available at `cert.json`. +1. Service account certificate: This allows access to your Firebase project through a service account +which is required for all integration tests. This can be downloaded as a JSON file from the +**Settings > Service Accounts** tab of the Firebase console when you click the +**Generate new private key** button. Copy the file into the repo so it's available at `cert.json`. -2. Web API key: This is displayed in the **'Settings > General'** tab of the Firebase console +2. Web API key: This allows for Auth sign-in needed for some Authentication and Tenant Management +integration tests. This is displayed in the **Settings > General** tab of the Firebase console after enabling Authentication as described in the steps below. Copy it and save to a new text file at `apikey.txt`. @@ -184,65 +186,70 @@ Set up your Firebase project as follows: 1. Enable Authentication: - 1. Go to the Firebase Console, and select **'Authentication'** from the **'Build'** menu. - 2. Click on **'Get Started'**. - 3. Select **'Sign-in method > Add new provider > Email/Password'** then enable both the - **'Email/Password'** and **'Email link (passwordless sign-in)'** options. + 1. Go to the Firebase Console, and select **Authentication** from the **Build** menu. + 2. Click on **Get Started**. + 3. Select **Sign-in method > Add new provider > Email/Password** then enable both the + **Email/Password** and **Email link (passwordless sign-in)** options. 2. Enable Firestore: - 1. Go to the Firebase Console, and select **'Firestore Database'** from the **'Build'** menu. - 2. Click on the **'Create database'** button. You can choose to set up Firestore either in + 1. Go to the Firebase Console, and select **Firestore Database** from the **Build** menu. + 2. Click on the **Create database** button. You can choose to set up Firestore either in the production mode or in the test mode. 3. Enable Realtime Database: - 1. Go to the Firebase Console, and select **'Realtime Database'** from the **'Build'** menu. - 2. Click on the **'Create database'** button. You can choose to set up the Realtime database + 1. Go to the Firebase Console, and select **Realtime Database** from the **Build** menu. + 2. Click on the **Create Database** button. You can choose to set up the Realtime Database either in the locked mode or in the test mode. - 3. In the **'Data'** tab click on the kebab menu (3 dots) and select **'Create Database'**. - 4. Enter your Project ID (Found in the **'General'** tab in **'Account Settings'**) as the - **'Realtime Database reference'**. Again, you can choose to set up the Realtime database + + > **Note:** Integration tests are not run against the default Realtime Database reference and are + instead run against a database created at `https://{PROJECT_ID}.firebaseio.com`. + This second Realtime Database reference is created in the following steps. + + 3. In the **Data** tab click on the kebab menu (3 dots) and select **Create Database**. + 4. Enter your Project ID (Found in the **General** tab in **Account Settings**) as the + **Realtime Database reference**. Again, you can choose to set up the Realtime Database either in the locked mode or in the test mode. 4. Enable Storage: - 1. Go to the Firebase Console, and select **'Storage'** from the **'Build'** menu. - 2. Click on the **'Get started'** button. You can choose to set up the Realtime database + 1. Go to the Firebase Console, and select **Storage** from the **Build** menu. + 2. Click on the **Get started** button. You can choose to set up Cloud Storage either in the production mode or in the test mode. 5. Enable the Firebase ML API: 1. Go to the - [Google Developers Console | Firebase ML API](https://console.developers.google.com/apis/api/firebaseml.googleapis.com/overview) + [Google Cloud console | Firebase ML API](https://console.cloud.google.com/apis/api/firebaseml.googleapis.com/overview) and make sure your project is selected. - 2. If the API is not already enabled, click **'Enable'**. + 2. If the API is not already enabled, click **Enable**. 6. Enable the IAM API: - 1. Go to the[Google Cloud Platform Console](https://console.cloud.google.com) - and make sureyour Firebase project is selected. - 2. Select **'APIs & Services'** from the main menu, and click the - **'ENABLE APIS AND SERVICES'** button. - 3. Search for and enable **'Identity and Access Management (IAM) API'** by Google Enterprise API. + 1. Go to the [Google Cloud console](https://console.cloud.google.com) + and make sure your Firebase project is selected. + 2. Select **APIs & Services** from the main menu, and click the + **ENABLE APIS AND SERVICES** button. + 3. Search for and enable **Identity and Access Management (IAM) API** by Google Enterprise API. 7. Enable Tenant Management: 1. Go to - [Google Developers Console | Identity Platform](https://console.cloud.google.com/customer-identity/) - and if it is not already enabled, click **'Enable'**. - 2. Then follow - [this guide](https://cloud.google.com/identity-platform/docs/multi-tenancy-quickstart#enabling_multi-tenancy) - to enable multi-tenancy. + [Google Cloud console | Identity Platform](https://console.cloud.google.com/customer-identity/) + and if it is not already enabled, click **Enable**. + 2. Then + [enable multi-tenancy](https://cloud.google.com/identity-platform/docs/multi-tenancy-quickstart#enabling_multi-tenancy) + for your project. -8. Ensure your service account has the **'Firebase Authentication Admin'** role. This is required +8. Ensure your service account has the **Firebase Authentication Admin** role. This is required to ensure that exported user records contain the password hashes of the user accounts: - 1. Go to [Google Cloud Platform Console / IAM & admin](https://console.cloud.google.com/iam-admin). - 2. Find your service account in the list. If not added click the **'pencil'** icon to edit its + 1. Go to [Google Cloud console | IAM & admin](https://console.cloud.google.com/iam-admin). + 2. Find your service account in the list. If not added click the **pencil** icon to edit its permissions. - 3. Click **'ADD ANOTHER ROLE'** and choose **'Firebase Authentication Admin'**. - 4. Click **'SAVE'**. + 3. Click **ADD ANOTHER ROLE** and choose **Firebase Authentication Admin**. + 4. Click **SAVE**. Now you can invoke the integration test suite as follows: