fix: support firebase-admin v14

v14 removed the legacy namespaced API from the root firebase-admin entry
point, so `firestore(...)` was undefined and makeDocumentSnapshot threw.
Move to the modular subpaths (getFirestore, DocumentReference, GeoPoint,
Timestamp from firebase-admin/firestore; App, deleteApp, initializeApp,
AppOptions from firebase-admin/app).

The DocumentReference branch of objectToValueProto read a `_referencePath`
internal that no longer exists, emitting `projects//databases//<path>`.
It now reads projectId and databaseId off the Firestore instance and
includes the missing `documents` segment. The old spec assertion could
not catch this because DocumentReference.toString() returned
"[object Object]" on the bundled @google-cloud/firestore.

Drops admin ^8 and ^9 from peerDependencies. The modular subpaths have no
exports entry before v10, and this package has already imported
firebase-admin/firestore since v3.

Author: IzaakGough

package.json

@@ -52,7 +52,7 @@
     "chai": "^4.2.0",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^10.1.8",
-    "firebase-admin": "^12.0.0",
+    "firebase-admin": "^14.3.0",
     "firebase-functions": "^4.9.0",
     "firebase-tools": "^13.15.4",
     "mocha": "^11.7.6",
@@ -61,7 +61,7 @@
     "typescript": "^5.5.4"
   },
   "peerDependencies": {
-    "firebase-admin": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0",
+    "firebase-admin": "^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0",
     "firebase-functions": ">=4.9.0",
     "jest": ">=28.0.0"
   },

spec/app.spec.ts

@@ -22,7 +22,7 @@
 
 import { expect } from 'chai';
 import * as sinon from 'sinon';
-import * as firebase from 'firebase-admin';
+import * as adminApp from 'firebase-admin/app';
 
 import { testApp } from '../src/app';
 import { FirebaseFunctionsTest } from '../src/lifecycle';
@@ -42,34 +42,27 @@ describe('app', () => {
   });
 
   describe('#getApp', () => {
-    const spy = sinon.spy(firebase, 'initializeApp');
-
     afterEach(() => {
-      spy.resetHistory();
       appInstance.deleteApp();
     });
 
     it('should initialize a new app if appSingleton does not exist', () => {
-      appInstance.getApp();
-      expect(spy.called).to.be.true;
+      const app = appInstance.getApp();
+      expect(app.name).to.equal('firebase-functions-test');
     });
 
     it('should only initialize app once', () => {
-      appInstance.getApp();
-      appInstance.getApp();
-      expect(spy.calledOnce).to.be.true;
+      expect(appInstance.getApp()).to.equal(appInstance.getApp());
     });
   });
 
   describe('#deleteApp', () => {
     it('deletes appSingleton if it exists', () => {
-      const spy = sinon.spy();
-      appInstance.appSingleton = {
-        delete: spy,
-      };
+      const app = appInstance.getApp();
+      expect(adminApp.getApps()).to.include(app);
       appInstance.deleteApp();
-      expect(spy.called).to.be.true;
       expect(appInstance.appSingleton).to.equal(undefined);
+      expect(adminApp.getApps()).to.not.include(app);
     });
 
     it('does not throw an error if there are no apps to delete', () => {

spec/providers/firestore.spec.ts

@@ -1,5 +1,11 @@
 import { expect } from 'chai';
-import * as firebase from 'firebase-admin';
+import { deleteApp, initializeApp } from 'firebase-admin/app';
+import {
+  DocumentReference,
+  GeoPoint,
+  getFirestore,
+  Timestamp,
+} from 'firebase-admin/firestore';
 import * as sinon from 'sinon';
 import * as http from 'http';
 import { FeaturesList } from '../../src/features';
@@ -51,7 +57,7 @@ describe('providers/firestore', () => {
   });
 
   it('should allow geopoints with makeDocumentSnapshot', () => {
-    const hq = new firebase.firestore.GeoPoint(47.6703, 122.1971);
+    const hq = new GeoPoint(47.6703, 122.1971);
     const snapshot = test.firestore.makeDocumentSnapshot(
       { geopoint: hq },
       'collection/doc-id'
@@ -67,29 +73,30 @@ describe('providers/firestore', () => {
       'collection/doc-id'
     );
 
-    expect(snapshot.data().time).to.be.instanceof(firebase.firestore.Timestamp);
+    expect(snapshot.data().time).to.be.instanceof(Timestamp);
     expect(snapshot.data().time.toDate()).to.deep.equal(time);
   });
 
   it('should allow references with makeDocumentSnapshot', () => {
-    firebase.initializeApp({
+    initializeApp({
       projectId: 'not-a-project',
     });
 
-    const ref = firebase.firestore().doc('collection/doc-id');
+    const ref = getFirestore().doc('collection/doc-id');
     const snapshot = test.firestore.makeDocumentSnapshot(
       { ref },
       'collection/doc-id'
     );
 
-    expect(snapshot.data().ref).to.be.instanceOf(
-      firebase.firestore.DocumentReference
+    expect(snapshot.data().ref).to.be.instanceOf(DocumentReference);
+    expect(snapshot.data().ref.path).to.equal(ref.path);
+    expect(snapshot.data().ref.formattedName).to.equal(
+      'projects/not-a-project/databases/(default)/documents/collection/doc-id'
     );
-    expect(snapshot.data().ref.toString()).to.equal(ref.toString());
   });
 
   it('should use firebaseApp projectId in makeDocumentSnapshot options', async () => {
-    const customApp = firebase.initializeApp(
+    const customApp = initializeApp(
       {
         projectId: 'custom-project',
       },
@@ -112,7 +119,7 @@ describe('providers/firestore', () => {
         'projects/custom-project/databases/(default)/documents/collection/doc-id'
       );
     } finally {
-      await customApp.delete();
+      deleteApp(customApp);
     }
   });
 

src/app.ts

@@ -20,7 +20,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-import * as firebase from 'firebase-admin';
+import { App as AdminApp, deleteApp, initializeApp } from 'firebase-admin/app';
 
 /** @internal */
 export function testApp(): testApp.App {
@@ -36,15 +36,15 @@ export namespace testApp {
   export let init = () => (singleton = new testApp.App());
 
   export class App {
-    appSingleton: firebase.app.App;
+    appSingleton: AdminApp;
     constructor() {}
 
-    getApp(): firebase.app.App {
+    getApp(): AdminApp {
       if (typeof this.appSingleton === 'undefined') {
         const config = process.env.FIREBASE_CONFIG
           ? JSON.parse(process.env.FIREBASE_CONFIG)
           : {};
-        this.appSingleton = firebase.initializeApp(
+        this.appSingleton = initializeApp(
           config,
           // Give this app a name so it does not conflict with apps that user initialized.
           'firebase-functions-test'
@@ -55,7 +55,7 @@ export namespace testApp {
 
     deleteApp() {
       if (this.appSingleton) {
-        this.appSingleton.delete();
+        deleteApp(this.appSingleton);
         delete this.appSingleton;
       }
     }

src/index.ts

@@ -20,7 +20,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-import { AppOptions } from 'firebase-admin';
+import { AppOptions } from 'firebase-admin/app';
 import { merge } from 'lodash';
 
 import { FirebaseFunctionsTest } from './lifecycle';

src/lifecycle.ts

@@ -21,7 +21,7 @@
 // SOFTWARE.
 
 import { isEmpty } from 'lodash';
-import { AppOptions } from 'firebase-admin';
+import { AppOptions } from 'firebase-admin/app';
 import { forEach } from 'lodash';
 
 import { testApp } from './app';

src/providers/database.ts

@@ -21,7 +21,7 @@
 // SOFTWARE.
 
 import { database, Change } from 'firebase-functions/v1';
-import { app } from 'firebase-admin';
+import { App } from 'firebase-admin/app';
 
 import { testApp } from '../app';
 
@@ -36,7 +36,7 @@ export function makeDataSnapshot(
    * You do not need to supply this parameter if you supplied Firebase config values when initializing
    * firebase-functions-test.
    */
-  firebaseApp?: app.App,
+  firebaseApp?: App,
   /**
    * The RTDB instance to use when creating snapshot. This will override the `firebaseApp` parameter.
    * If omitted the default RTDB instance is used.

src/providers/firestore.ts

@@ -21,17 +21,21 @@
 // SOFTWARE.
 
 import { Change } from 'firebase-functions/v1';
-import { firestore, app } from 'firebase-admin';
 import { has, get, isEmpty, isPlainObject, mapValues } from 'lodash';
 import { inspect } from 'util';
 
 import { testApp } from '../app';
 
 import * as http from 'http';
 import {
+  DocumentReference,
   DocumentSnapshot,
+  GeoPoint,
+  getFirestore,
   QueryDocumentSnapshot,
+  Timestamp,
 } from 'firebase-admin/firestore';
+import { App } from 'firebase-admin/app';
 
 function dateToTimestampProto(
   timeString?: string
@@ -61,7 +65,7 @@ export interface DocumentSnapshotOptions {
   /** The Firebase app that the Firestore database belongs to. You do not need to supply
    * this parameter if you supplied Firebase config values when initializing firebase-functions-test.
    */
-  firebaseApp?: app.App;
+  firebaseApp?: App;
 }
 
 /** Create a DocumentSnapshot. */
@@ -77,10 +81,10 @@ export function makeDocumentSnapshot(
   let firestoreService;
   let project;
   if (options?.firebaseApp) {
-    firestoreService = firestore(options.firebaseApp);
+    firestoreService = getFirestore(options.firebaseApp);
     project = options.firebaseApp.options.projectId;
   } else {
-    firestoreService = firestore(testApp().getApp());
+    firestoreService = getFirestore(testApp().getApp());
     project = process.env.GCLOUD_PROJECT;
   }
 
@@ -107,7 +111,7 @@ export function makeDocumentSnapshot(
 /** Fetch an example document snapshot already populated with data. Can be passed into a wrapped
  * Firestore onCreate or onDelete function.
  */
-export function exampleDocumentSnapshot(): firestore.DocumentSnapshot {
+export function exampleDocumentSnapshot(): DocumentSnapshot {
   return makeDocumentSnapshot(
     {
       aString: 'foo',
@@ -124,7 +128,7 @@ export function exampleDocumentSnapshot(): firestore.DocumentSnapshot {
 /** Fetch an example Change object of document snapshots already populated with data.
  * Can be passed into a wrapped Firestore onUpdate or onWrite function.
  */
-export function exampleDocumentSnapshotChange(): Change<firestore.DocumentSnapshot> {
+export function exampleDocumentSnapshotChange(): Change<DocumentSnapshot> {
   return Change.fromObjects(
     makeDocumentSnapshot(
       {
@@ -205,24 +209,33 @@ export function objectToValueProto(data: object) {
         bytesValue: val,
       };
     }
-    if (val instanceof firestore.DocumentReference) {
-      const projectId: string = get(val, '_referencePath.projectId');
-      const database: string = get(val, '_referencePath.databaseId');
+    if (val instanceof DocumentReference) {
+      // projectId and databaseId live on the Firestore instance, not on the
+      // reference, and neither has a public accessor across the supported
+      // firebase-admin range.
+      const projectId: string =
+        get(val, 'firestore.projectId') ||
+        get(val, 'firestore._settings.projectId');
+      const databaseId: string =
+        get(val, 'firestore.databaseId') ||
+        get(val, 'firestore._settings.databaseId') ||
+        '(default)';
       const referenceValue: string = [
         'projects',
         projectId,
         'databases',
-        database,
+        databaseId,
+        'documents',
         val.path,
       ].join('/');
       return { referenceValue };
     }
-    if (val instanceof firestore.Timestamp) {
+    if (val instanceof Timestamp) {
       return {
         timestampValue: val.toDate().toISOString(),
       };
     }
-    if (val instanceof firestore.GeoPoint) {
+    if (val instanceof GeoPoint) {
       return {
         geoPointValue: {
           latitude: val.latitude,

tsconfig.json

@@ -6,7 +6,8 @@
     "outDir": ".tmp",
     "sourceMap": true,
     "target": "es6",
-    "typeRoots": ["node_modules/@types"]
+    "typeRoots": ["node_modules/@types"],
+    "skipLibCheck": true
   },
   "include": ["src/**/*.ts", "spec/**/*.ts"]
 }

tsconfig.release.json

@@ -7,7 +7,8 @@
     "outDir": "lib",
     "stripInternal": true,
     "target": "es6",
-    "typeRoots": ["node_modules/@types"]
+    "typeRoots": ["node_modules/@types"],
+    "skipLibCheck": true
   },
   "files": ["src/index.ts"]
 }