Add testing support for 2nd gen firestore triggers (#200)

* firestore onDocumentCreated trigger

* on doc updated, written, deleted & unit tests

* on doc written unit tests

* don't overwrite user's mocked before/after data if they didn't mock the other

Author: blidd-google

CHANGELOG.md

@@ -0,0 +1 @@
+- Add testing support for 2nd gen firestore triggers (#200).

package-lock.json

@@ -47,7 +47,7 @@
     "@types/mocha": "^5.2.7",
     "chai": "^4.2.0",
     "firebase-admin": "^10.1.0",
-    "firebase-functions": "^4.0.0-rc.0",
+    "firebase-functions": ">=4.3.0",
     "firebase-tools": "^8.9.2",
     "mocha": "^6.2.2",
     "prettier": "^1.19.1",
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "firebase-admin": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
-    "firebase-functions": "^4.0.0",
+    "firebase-functions": ">=4.3.0",
     "jest": ">=28.0.0"
   },
   "engines": {

package.json

@@ -34,9 +34,12 @@ import {
   testLab,
   eventarc,
   https,
+  firestore,
 } from 'firebase-functions/v2';
 import { defineString } from 'firebase-functions/params';
 import { makeDataSnapshot } from '../src/providers/database';
+import { makeDocumentSnapshot } from '../src/providers/firestore';
+import { inspect } from 'util';
 
 describe('v2', () => {
   describe('#wrapV2', () => {
@@ -460,6 +463,275 @@ describe('v2', () => {
       });
     });
 
+    describe('firestore', () => {
+      describe('document path', () => {
+        it('should resolve default document path', () => {
+          const cloudFn = firestore.onDocumentCreated('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const cloudEvent = cloudFnWrap().cloudEvent;
+
+          expect(cloudEvent.document).equal('foo/bar/baz');
+        });
+
+        it('should resolve default document given StringParam', () => {
+          process.env.doc_path = 'foo/StringParam/baz';
+          const cloudFn = firestore.onDocumentCreated('', handler);
+          cloudFn.__endpoint.eventTrigger.eventFilterPathPatterns.document = defineString(
+            'doc_path'
+          );
+          const cloudFnWrap = wrapV2(cloudFn);
+          const cloudEvent = cloudFnWrap().cloudEvent;
+
+          expect(cloudEvent.document).equal('foo/StringParam/baz');
+        });
+
+        it('should resolve using params', () => {
+          const cloudFn = firestore.onDocumentCreated('users/{user}', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const partial = {
+            params: {
+              user: '123',
+            },
+          };
+          const cloudEvent = cloudFnWrap(partial).cloudEvent;
+
+          expect(cloudEvent.document).equal('users/123');
+        });
+
+        it('should resolve with undefined string if variable is missing', () => {
+          const cloudFn = firestore.onDocumentCreated('users/{user}', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const partial = {
+            params: {},
+          };
+          const cloudEvent = cloudFnWrap(partial).cloudEvent;
+
+          expect(cloudEvent.document).equal('users/undefined');
+        });
+      });
+
+      describe('document options', () => {
+        it('resolves default document options correctly', () => {
+          const cloudFn = firestore.onDocumentCreated('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const cloudEvent = cloudFnWrap().cloudEvent;
+
+          expect(cloudEvent.document).equal('foo/bar/baz');
+          expect(cloudEvent.database).equal('(default)');
+          expect(cloudEvent.namespace).equal('(default)');
+        });
+
+        it('reads custom DocumentOptions correctly', () => {
+          const documentOptions = {
+            document: 'foo/bar/baz',
+            database: 'custom-database',
+            namespace: 'custom-namespace',
+          };
+          const cloudFn = firestore.onDocumentCreated(documentOptions, handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const cloudEvent = cloudFnWrap().cloudEvent;
+
+          expect(cloudEvent.document).equal(documentOptions.document);
+          expect(cloudEvent.database).equal(documentOptions.database);
+          expect(cloudEvent.namespace).equal(documentOptions.namespace);
+        });
+      });
+
+      describe('firestore.onDocumentCreated', () => {
+        it('should update CloudEvent appropriately', () => {
+          const cloudFn = firestore.onDocumentCreated('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const cloudEvent = cloudFnWrap().cloudEvent;
+
+          expect(cloudEvent).deep.equal({
+            id: cloudEvent.id,
+            time: cloudEvent.time,
+            specversion: '1.0',
+            type: 'google.cloud.firestore.document.v1.created',
+            source: '',
+
+            data: cloudEvent.data,
+            location: 'us-central1',
+            project: 'testproject',
+            database: '(default)',
+            namespace: '(default)',
+            document: 'foo/bar/baz',
+            params: {},
+          });
+        });
+
+        it('should use overridden data', () => {
+          const cloudFn = firestore.onDocumentCreated('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const docData = { foo: 'bar' };
+          const data = makeDocumentSnapshot(docData, 'foo/bar/baz');
+          const cloudEvent = cloudFnWrap({ data }).cloudEvent;
+
+          expect(cloudEvent.data.data()).deep.equal(docData);
+        });
+
+        it('should accept json data', () => {
+          const cloudFn = firestore.onDocumentCreated('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const docData = { foo: 'bar' };
+          const cloudEvent = cloudFnWrap({ data: docData }).cloudEvent;
+
+          expect(cloudEvent.data.data()).deep.equal(docData);
+        });
+      });
+
+      describe('firestore.onDocumentDeleted()', () => {
+        it('should update CloudEvent appropriately', () => {
+          const cloudFn = firestore.onDocumentDeleted('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const cloudEvent = cloudFnWrap().cloudEvent;
+
+          expect(cloudEvent).deep.equal({
+            id: cloudEvent.id,
+            time: cloudEvent.time,
+            specversion: '1.0',
+            type: 'google.cloud.firestore.document.v1.deleted',
+            source: '',
+
+            data: cloudEvent.data,
+            location: 'us-central1',
+            project: 'testproject',
+            database: '(default)',
+            namespace: '(default)',
+            document: 'foo/bar/baz',
+            params: {},
+          });
+        });
+
+        it('should use overridden data', () => {
+          const cloudFn = firestore.onDocumentDeleted('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const docData = { foo: 'bar' };
+          const data = makeDocumentSnapshot(docData, 'foo/bar/baz');
+          const cloudEvent = cloudFnWrap({ data }).cloudEvent;
+
+          expect(cloudEvent.data.data()).deep.equal(docData);
+        });
+
+        it('should accept json data', () => {
+          const cloudFn = firestore.onDocumentDeleted('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const docData = { foo: 'bar' };
+          const cloudEvent = cloudFnWrap({ data: docData }).cloudEvent;
+
+          expect(cloudEvent.data.data()).deep.equal(docData);
+        });
+      });
+
+      describe('firestore.onDocumentUpdated', () => {
+        it('should update CloudEvent appropriately', () => {
+          const cloudFn = firestore.onDocumentUpdated('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const cloudEvent = cloudFnWrap().cloudEvent;
+
+          expect(cloudEvent).deep.equal({
+            id: cloudEvent.id,
+            time: cloudEvent.time,
+            specversion: '1.0',
+            type: 'google.cloud.firestore.document.v1.updated',
+            source: '',
+
+            data: cloudEvent.data,
+            location: 'us-central1',
+            project: 'testproject',
+            database: '(default)',
+            namespace: '(default)',
+            document: 'foo/bar/baz',
+            params: {},
+          });
+        });
+
+        it('should use overridden data', () => {
+          const cloudFn = firestore.onDocumentUpdated('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+
+          const afterDataVal = { snapshot: 'after' };
+          const after = makeDocumentSnapshot(afterDataVal, 'foo/bar/baz');
+
+          const beforeDataVal = { snapshot: 'before' };
+          const before = makeDocumentSnapshot(beforeDataVal, 'foo/bar/baz');
+
+          const data = { before, after };
+          const cloudEvent = cloudFnWrap({ data }).cloudEvent;
+
+          expect(cloudEvent.data.before.data()).deep.equal(beforeDataVal);
+          expect(cloudEvent.data.after.data()).deep.equal(afterDataVal);
+        });
+
+        it('should accept json data', () => {
+          const cloudFn = firestore.onDocumentUpdated('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const afterDataVal = { snapshot: 'after' };
+          const beforeDataVal = { snapshot: 'before' };
+
+          const data = { before: beforeDataVal, after: afterDataVal };
+          const cloudEvent = cloudFnWrap({ data }).cloudEvent;
+
+          expect(cloudEvent.data.before.data()).deep.equal(beforeDataVal);
+          expect(cloudEvent.data.after.data()).deep.equal(afterDataVal);
+        });
+      });
+
+      describe('firestore.onDocumentWritten', () => {
+        it('should update CloudEvent appropriately', () => {
+          const cloudFn = firestore.onDocumentWritten('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const cloudEvent = cloudFnWrap().cloudEvent;
+
+          expect(cloudEvent).deep.equal({
+            id: cloudEvent.id,
+            time: cloudEvent.time,
+            specversion: '1.0',
+            type: 'google.cloud.firestore.document.v1.written',
+            source: '',
+
+            data: cloudEvent.data,
+            location: 'us-central1',
+            project: 'testproject',
+            database: '(default)',
+            namespace: '(default)',
+            document: 'foo/bar/baz',
+            params: {},
+          });
+        });
+
+        it('should use overridden data', () => {
+          const cloudFn = firestore.onDocumentWritten('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+
+          const afterDataVal = { snapshot: 'after' };
+          const after = makeDocumentSnapshot(afterDataVal, 'foo/bar/baz');
+
+          const beforeDataVal = { snapshot: 'before' };
+          const before = makeDocumentSnapshot(beforeDataVal, 'foo/bar/baz');
+
+          const data = { before, after };
+          const cloudEvent = cloudFnWrap({ data }).cloudEvent;
+
+          expect(cloudEvent.data.before.data()).deep.equal(beforeDataVal);
+          expect(cloudEvent.data.after.data()).deep.equal(afterDataVal);
+        });
+
+        it('should accept json data', () => {
+          const cloudFn = firestore.onDocumentWritten('foo/bar/baz', handler);
+          const cloudFnWrap = wrapV2(cloudFn);
+          const afterDataVal = { snapshot: 'after' };
+          const beforeDataVal = { snapshot: 'before' };
+
+          const data = { before: beforeDataVal, after: afterDataVal };
+          const cloudEvent = cloudFnWrap({ data }).cloudEvent;
+
+          expect(cloudEvent.data.before.data()).deep.equal(beforeDataVal);
+          expect(cloudEvent.data.after.data()).deep.equal(afterDataVal);
+        });
+      });
+    });
+
     describe('database', () => {
       describe('ref', () => {
         it('should resolve default ref', () => {
@@ -488,23 +760,23 @@ describe('v2', () => {
           expect(cloudEvent.ref).equal('foo/StringParam/baz');
         });
 
-        it.skip('should resolve default ref given TernaryExpression', () => {
-          const ref1 = defineString('rtdb_ref_1');
-          process.env.rtdb_ref_1 = 'foo/StringParam/1';
-          const ref2 = defineString('rtdb_ref_2');
-          process.env.rtdb_ref_2 = 'foo/StringParam/2';
-          const referenceOptions = {
-            ref: '',
-            instance: 'instance-1',
-          };
-          const cloudFn = database.onValueCreated(referenceOptions, handler);
-          cloudFn.__endpoint.eventTrigger.eventFilterPathPatterns.ref = ref1
-            .equals('aa')
-            .then('rtdb_ref_1', 'rtdb_ref_2');
-          const cloudFnWrap = wrapV2(cloudFn);
-          const cloudEvent = cloudFnWrap().cloudEvent;
-          expect(cloudEvent.ref).equal('rtdb_ref_2');
-        });
+        // it('should resolve default ref given TernaryExpression', () => {
+        //   const ref1 = defineString('rtdb_ref_1');
+        //   process.env.rtdb_ref_1 = 'foo/StringParam/1';
+        //   const ref2 = defineString('rtdb_ref_2');
+        //   process.env.rtdb_ref_2 = 'foo/StringParam/2';
+        //   const referenceOptions = {
+        //     ref: '',
+        //     instance: 'instance-1',
+        //   };
+        //   const cloudFn = database.onValueCreated(referenceOptions, handler);
+        //   cloudFn.__endpoint.eventTrigger.eventFilterPathPatterns.ref = ref1
+        //     .equals('aa')
+        //     .then('rtdb_ref_1', 'rtdb_ref_2');
+        //   const cloudFnWrap = wrapV2(cloudFn);
+        //   const cloudEvent = cloudFnWrap().cloudEvent;
+        //   expect(cloudEvent.ref).equal('rtdb_ref_2');
+        // });
 
         it('should resolve using params', () => {
           const referenceOptions = {

spec/v2.spec.ts

@@ -4,6 +4,10 @@ import {
   database,
   pubsub,
 } from 'firebase-functions/v2';
+import {
+  DocumentSnapshot,
+  QueryDocumentSnapshot,
+} from 'firebase-admin/firestore';
 import { LIST_OF_MOCK_CLOUD_EVENT_PARTIALS } from './mocks/partials';
 import { DeepPartial } from './types';
 import { Change } from 'firebase-functions';
@@ -41,7 +45,13 @@ export function generateMockCloudEvent<EventType extends CloudEvent<unknown>>(
   return null;
 }
 
-const IMMUTABLE_DATA_TYPES = [database.DataSnapshot, Change, pubsub.Message];
+const IMMUTABLE_DATA_TYPES = [
+  database.DataSnapshot,
+  DocumentSnapshot,
+  QueryDocumentSnapshot,
+  Change,
+  pubsub.Message,
+];
 
 function mergeCloudEvents<EventType extends CloudEvent<unknown>>(
   generatedCloudEvent: EventType,