Test

Author: brianquinlan

.github/workflows/gcs_emulator_tests.yaml

@@ -47,7 +47,7 @@ jobs:
         with:
           check-port: '9199'
           emulators: 'storage'
-          project-id: 'test-project'
+        working-directory: packages/google_cloud_storage/emulator_test
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
       - uses: dart-lang/setup-dart@e51d8e571e22473a2ddebf0ef8a2123f0ab2c02c
         with:

packages/google_cloud_storage/emulator_test/README.md

@@ -1,20 +1,35 @@
 # Google Cloud Storage Emulator Tests
 
-Tests that verify that the Google Cloud Storage client library works correctly
-with the Firebase Storage Emulator.
+This directory contains integration tests that verify the compatibility of
+`package:google_cloud_storage` with the [Firebase Storage Emulator][].
 
-## Running these tests locally
+## Running Tests Locally
 
-To run these tests locally, the Firebase Storage Emulator must be running.
+To run these tests on your machine, you need to have the emulator running in one terminal session and execute the tests in another.
+
+### 1. Start the Firebase Emulator
+
+Navigate to this directory and start the storage emulator:
 
 ```bash
-# Run inside this directory.
+# From packages/google_cloud_storage/emulator_test
 firebase emulators:start
 ```
 
-and then:
+### 2. Run the Tests
+
+In a separate terminal, navigate to the root of the `google_cloud_storage` package and run the tests:
 
 ```bash
-# Run inside the google_cloud_storage directory
+# From packages/google_cloud_storage
 dart test emulator_test
 ```
+
+## Known Limitations
+
+The Firebase Storage Emulator is a high-fidelity implementation of the Cloud Storage for Firebase API, which is a subset of the full Google Cloud Storage JSON API. Consequently:
+
+- Some advanced GCS features (e.g., Object Retention/Lock, certain IAM configurations, or specific query parameters) may return a `NotImplementedException` (HTTP 501) or `BadRequestException`.
+- Always verify critical production logic against a live GCS project using the recorded API tests in the `test/` directory.
+
+[Firebase Storage Emulator]: https://firebase.google.com/docs/emulator-suite/connect_storage