New section documentation on how to perform local PubSub testing

docs/README.md

@@ -7,7 +7,6 @@ This directory contains advanced docs around the Functions Framework.
 ## TODO Docs
 
 - TODO: Run Multiple Cloud Functions [#23](https://github.com/GoogleCloudPlatform/functions-framework-nodejs/issues/23)
-- TODO: Pub/Sub Trigger [#37](https://github.com/GoogleCloudPlatform/functions-framework-nodejs/issues/37)
 - TODO: Deploy to Cloud Run [#28](https://github.com/GoogleCloudPlatform/functions-framework-nodejs/pull/28)
 
 ## Debugging functions
@@ -41,3 +40,76 @@ URL: http://localhost:8080/
 ```
 
 You can now use an IDE or other tooling to add breakpoints, step through your code and debug your function.
+
+## Local testing of cloud events
+The setup for cloud functions that accept events is very similar to the instructions in the quickstart, with the following adjustments:
+
+In your package.json, add a signature type (in bold) to your start command:
+<pre>
+  "scripts": {
+    "start": "functions-framework --target=helloWorld <b>--signature-type=event"</b>
+  }
+</pre>
+
+Upon running ```sh npm start ```, you'll see the function is still being served at http://localhost:8080/. However it is no longer accessible via GET requests from the browser. Instead, send a POST request where the request body conforms to the API defined by [push subscriptions](https://cloud.google.com/pubsub/docs/push).
+
+### Submitting POST request to simulating a pubsub message
+
+Create mockPubsub.json file with the following contents:
+```json
+{
+  "message": {
+    "attributes": {
+      "key": "value"
+    },
+    "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
+    "messageId": "136969346945"
+  },
+  "subscription": "projects/myproject/subscriptions/mysubscription"
+}
+```
+
+The file can be in any folder on your computer. From the terminal, goto the directory where ```mockPubsub.json``` is located, and run the following command assuming your cloud function is hosted locally on port 8080:
+```sh
+curl -d "@mockPubsub.json" -X POST \
+  -H "Ce-Type: true" \
+  -H "Ce-Specversion: true" \
+  -H "Ce-Source: true" \
+  -H "Ce-Id: true" \
+  http://localhost:8080
+```
+
+> In order to simulate a Cloud Event, you need to add the ```Ce-*``` headers, along with a _truthy_ value, to the request.
+
+ ### Using pubsub emulator
+
+ Another way to test your cloud function pubsub endpoint is to use the [pubsub emulator](https://cloud.google.com/pubsub/docs/emulator). This allows you to use the pubsub notification from another service to trigger your cloud function.
+
+ The high level approach is to:
+ 1. Start the pubsub emulator
+ 2. Use the pubsub client library to create a subscription and set the pushEndpoint to http://localhost:8080.
+
+ After that, all notifications to the subscription topic will be pushed to your cloud function.
+
+ Sample script for creating subscription with pushEndpoint:
+
+ ```js
+{ PubSub } require('@google-cloud/pubsub');
+
+async function main() {
+  const pubsub = new PubSub({
+    apiEndpoint: 'localhost:8085', // Pubsub emulator endpoint
+    projectId: 'myproject',
+  });
+  const topic = await pubsub.topic('my-topic');
+  const [topicExists] = await topic.exists();
+  if (!topicExists) {
+    await topic.create();
+  }
+  const createSubscriptionResponse = await topic.createSubscription('my_subscription', {
+    pushEndpoint: 'https://localhost:8080',
+  });
+}
+
+main();
+ ```