Edit example and add necessary snippets

Change-Id: I06416465bcaafd58d942ac150da0444479a71386

Author: Lauren Long

quickstarts/uppercase/README.md

@@ -9,9 +9,9 @@ This sample app does two things:
  - Create messages in the Firebase Realtime Database using a simple HTTPS request which is handled by an HTTPS Firebase Function. Writing to the Realtime Database is done using the Firebase Admin SDK. 
  - When a message gets added in the Realtime Database, a Firebase Function triggers and automatically makes these messages all uppercase.
 
-## Deploy and test
+## Deploy and try out
 
-To deploy and test the sample:
+To deploy and try out the sample:
 
  - Create a Firebase project on the [Firebase Console](https://console.firebase.google.com)
  - Install the required dependencies by running `npm install` in the `functions` directory
@@ -20,8 +20,20 @@ To deploy and test the sample:
 
  The function executes and redirects the browser to the Firebase console at the database location where the text string was stored. You should see your text value displayed in the console and uppercase.
 
+## Run unit tests
 
+The test folder has unit tests written with `firebase-functions-test`. There are 2 sets of tests: online and offline.
 
+To run the offline tests: run `npm test` inside the functions folder.
+
+To run the online tests:
+ - Replace the `projectConfig` variable in `test/test.online.js` with configuration values from your project.
+ - Download a service account key by following these instructions:
+ ..* Open the Service Accounts pane of the Google Cloud Console.
+ ..* Select the App Engine default service account, and use the options menu at right to select Create key.
+ ..* When prompted, select JSON for the key type, and click Create.
+ - Save the file in the test folder, and name it `service-account-key.json`
+ - Run `npm run test-online` inside the functions folder.
 
 ## Contributing
 

quickstarts/uppercase/functions/package.json

@@ -15,8 +15,9 @@
   },
   "scripts": {
     "ci-test": "npm install && npm run test",
-    "test-online": "./node_modules/.bin/mocha --reporter spec test/test.online.js --exit",
-    "test-offline": "./node_modules/.bin/mocha --reporter spec test/test.offline.js --exit",
+    "test": "npm run test-offline",
+    "test-online": "mocha --reporter spec test/test.online.js --exit",
+    "test-offline": "mocha --reporter spec test/test.offline.js --exit",
     "serve": "firebase serve --only functions",
     "shell": "firebase experimental:functions:shell",
     "start": "npm run shell",

quickstarts/uppercase/functions/test/test.offline.js

@@ -20,12 +20,6 @@
 const chai = require('chai');
 const assert = chai.assert;
 
-// Chai As Promised extends Chai so that a test function can be asynchronous with promises instead
-// of using callbacks. It is recommended when testing Cloud Functions for Firebase due to its heavy
-// use of Promises.
-const chaiAsPromised = require("chai-as-promised");
-chai.use(chaiAsPromised);
-
 // Sinon is a library used for mocking or verifying function calls in JavaScript.
 const sinon = require('sinon');
 
@@ -40,37 +34,37 @@ describe('Cloud Functions', () => {
   var myFunctions, adminInitStub;
 
   before(() => {
-    // Since index.js calls admin.initializeApp at the top of the file,
+    // [START stubAdminInit]
+    // If index.js calls admin.initializeApp at the top of the file,
     // we need to stub it out before requiring index.js. This is because the
     // functions will be executed as a part of the require process.
     // Here we stub admin.initializeApp to be a dummy function that doesn't do anything.
     adminInitStub = sinon.stub(admin, 'initializeApp');
     // Now we can require index.js and save the exports inside a namespace called myFunctions.
-    // This includes our cloud functions, which can now be accessed at myFunctions.makeUppercase
-    // and myFunctions.addMessage
     myFunctions = require('../index');
+    // [END stubAdminInit]
   });
 
   after(() => {
     // Restore admin.initializeApp() to its original method.
     adminInitStub.restore();
     // Do other cleanup tasks.
-    test.cleanUp();
+    test.cleanup();
   });
 
   describe('makeUpperCase', () => {
-    // Test Case: setting messages/11111/original to 'input' should cause 'INPUT' to be written to
-    // messages/11111/uppercase
+    // Test Case: setting messages/{pushId}/original to 'input' should cause 'INPUT' to be written to
+    // messages/{pushId}/uppercase
     it('should upper case input and write it to /uppercase', () => {
-
-      // [START stubDataRef]
+      // [START assertOffline]
       const childParam = 'uppercase';
       const setParam = 'INPUT';
       // Stubs are objects that fake and/or record function calls.
       // These are excellent for verifying that functions have been called and to validate the
       // parameters passed to those functions.
       const childStub = sinon.stub();
       const setStub = sinon.stub();
+      // [START fakeSnap]
       // The following lines creates a fake snapshot, 'snap', which returns 'input' when snap.val() is called,
       // and returns true when snap.ref.parent.child('uppercase').set('INPUT') is called.
       const snap = {
@@ -83,15 +77,13 @@ describe('Cloud Functions', () => {
       };
       childStub.withArgs(childParam).returns( { set: setStub });
       setStub.withArgs(setParam).returns(true);
-      // [END stubDataRef]
-
-      // [START verifyDataWrite]
-      // TODO
+      // [END fakeSnap]
+      // Wrap the makeUppercase function.
       const wrapped = test.wrap(myFunctions.makeUppercase);
       // Since we've stubbed snap.ref.parent.child(childParam).set(setParam) to return true if it was
       // called with the parameters we expect, we assert that it indeed returned true.
       return assert.equal(wrapped(snap), true);
-      // [END verifyDataWrite]
+      // [END assertOffline]
     })
   });
 
@@ -108,15 +100,13 @@ describe('Cloud Functions', () => {
     });
 
     it('should return a 303 redirect', (done) => {
-
-      // [START stubAdminDatabase]
       const refParam = '/messages';
       const pushParam = { original: 'input' };
       const databaseStub = sinon.stub();
       const refStub = sinon.stub();
       const pushStub = sinon.stub();
 
-      // The following 4 lines override the behavior of admin.database().ref('/messages')
+      // The following lines override the behavior of admin.database().ref('/messages')
       // .push({ original: 'input' }) to return a promise that resolves with { ref: 'new_ref' }.
       // This mimics the behavior of a push to the database, which returns an object containing a
       // ref property representing the URL of the newly pushed item.
@@ -126,9 +116,7 @@ describe('Cloud Functions', () => {
       refStub.withArgs(refParam).returns({ push: pushStub });
       pushStub.withArgs(pushParam).returns(Promise.resolve({ ref: 'new_ref' }));
 
-      // [END stubAdminDatabase]
-
-      // [START invokeHTTPS]
+      // [START assertHTTP]
       // A fake request object, with req.query.text set to 'input'
       const req = { query: {text: 'input'} };
       // A fake response object, with a stubbed redirect function which asserts that it is called
@@ -144,7 +132,7 @@ describe('Cloud Functions', () => {
       // Invoke addMessage with our fake request and response objects. This will cause the
       // assertions in the response object to be evaluated.
       myFunctions.addMessage(req, res);
-      // [END invokeHTTPS]
+      // [END assertHTTP]
     });
   });
 })

quickstarts/uppercase/functions/test/test.online.js

@@ -14,27 +14,23 @@
  * limitations under the License.
  */
 
-// You can run these unit tests by running "npm test" inside the uppercase/functions directory.
+// Follow the instructions in uppercase/README.md for running these tests
 
 // Chai is a commonly used library for creating unit test suites. It is easily extended with plugins.
 const chai = require('chai');
 const assert = chai.assert;
 
-// Chai As Promised extends Chai so that a test function can be asynchronous with promises instead
-// of using callbacks. It is recommended when testing Cloud Functions for Firebase due to its heavy
-// use of Promises.
-const chaiAsPromised = require("chai-as-promised");
-chai.use(chaiAsPromised);
-
 // Sinon is a library used for mocking or verifying function calls in JavaScript.
 const sinon = require('sinon');
 
 const admin = require('firebase-admin');
-// Require and initialize firebase-functions-test with your project's credentials and service account key.
-const test = require('firebase-functions-test')({
+// Require and initialize firebase-functions-test in "online mode" with your project's
+// credentials and service account key.
+const projectConfig = {
   projectId: 'my-project',
   databaseURL: 'https://my-project.firebaseio.com'
-}, './service-account-key.json');
+};
+const test = require('firebase-functions-test')(projectConfig, './service-account-key.json');
 
 describe('Cloud Functions', () => {
   var myFunctions;
@@ -48,7 +44,7 @@ describe('Cloud Functions', () => {
 
   after(() => {
     // Do cleanup tasks.
-    test.cleanUp();
+    test.cleanup();
     // Reset the database.
     admin.database().ref('messages').remove();
   });
@@ -57,10 +53,10 @@ describe('Cloud Functions', () => {
     // Test Case: setting messages/11111/original to 'input' should cause 'INPUT' to be written to
     // messages/11111/uppercase
     it('should upper case input and write it to /uppercase', () => {
+      // [START assertOnline]
       // Create a DataSnapshot with the value 'input' and the reference path 'messages/11111/original'.
       const snap = test.database.makeDataSnapshot('input', 'messages/11111/original');
 
-      // [START verifyDataWrite]
       // Wrap the makeUppercase function
       const wrapped = test.wrap(myFunctions.makeUppercase);
       // Call the wrapped function with the snapshot you constructed.
@@ -73,13 +69,12 @@ describe('Cloud Functions', () => {
           assert.equal(createdSnap.val(), 'INPUT');
         });
       });
-      // [END verifyDataWrite]
+      // [END assertOnline]
     })
   });
 
   describe('addMessage', () => {
     it('should return a 303 redirect', (done) => {
-      // [START invokeHTTPS]
       // A fake request object, with req.query.text set to 'input'
       const req = { query: {text: 'input'} };
       // A fake response object, with a stubbed redirect function which does some assertions
@@ -88,7 +83,7 @@ describe('Cloud Functions', () => {
           // Assert code is 303
           assert.equal(code, 303);
           // If the database push is successful, then the URL sent back will have the following format:
-          var expectedRef = new RegExp('https://ll-firestore-dev.firebaseio.com/messages/');
+          var expectedRef = new RegExp(projectConfig.databaseURL + '/messages/');
           assert.isTrue(expectedRef.test(url));
           done();
         }
@@ -97,7 +92,6 @@ describe('Cloud Functions', () => {
       // Invoke addMessage with our fake request and response objects. This will cause the
       // assertions in the response object to be evaluated.
       myFunctions.addMessage(req, res);
-      // [END invokeHTTPS]
     });
   });
 })