Testing and CI/CD

This guide covers best practices for testing and deploying Cloud Functions, discusses the types of tests you should use, and provides some instructions for example testing scenarios. This guide also has information on automatically running your tests and optionally redeploying your functions using a Continuous Integration and Deployment (CI/CD) platform such as Cloud Build.

Before you begin

Before starting this guide, set up your environment.

Frameworks

Node.js

The examples in this guide use AVA as a test framework to run tests and Sinon as a mocking framework to mock external dependencies.

An external dependency is a dependency that your function relies on that isn't a part of your function's code. Common examples of external dependencies are other Google Cloud Platform services and libraries installed using package managers such as npm.

Python

The examples in this guide use Pytest as a test framework to run tests and unittest as a mocking framework to mock external dependencies.

An external dependency is a dependency that your function relies on that isn't a part of your function's code. Common examples of external dependencies are other Google Cloud Platform services and libraries installed using package managers such as pip.

Go

The examples in this guide use the standard library testing package to run tests. However, the system tests have external dependencies.

An external dependency is a dependency that your function relies on that isn't a part of your function's code. Common examples of external dependencies are other Google Cloud Platform services and other packages you've downloaded.

Types of tests

There are three types of tests that you can use when working with Cloud Functions, each of which tests a different aspect of your code. They are listed below, from least to most thorough:

  • Unit tests
  • Integration tests
  • System tests

In general, more thorough tests take more time to complete. This document discusses these test types in detail, as well as how to strike a balance between speed and thoroughness.

Unit tests

Unit tests are narrowly-scoped tests for small, specific parts of your code. These tests are good for quickly verifying assumptions made during the development process, such as handling edge cases and input validation.

By design, unit tests do not test integration with any external dependencies, such as Cloud Functions itself or other Google Cloud Platform components. You can use your mocking framework to create mock versions of external dependencies.

For HTTP functions, tests should mock the wrapping HTTP framework. Confirm the function's behavior by combining testing and mocking frameworks and comparing your function's results to expected values.

Unit tests cannot detect changes in external dependencies. If these dependencies change, both the tested code and your mocks must be updated.

Integration tests

Integration tests validate interaction between parts of your code, and typically take a moderate amount of time to complete. For example, in Cloud Functions, integration tests can be used to test a function's usage of other GCP services such as Cloud Datastore or Cloud AutoML Vision.

The primary difference between unit tests and integration tests for Cloud Functions is that integration tests involve less mocking than unit tests. Integration tests should trigger and respond to Cloud events such as HTTP requests, Cloud Pub/Sub messages, or Storage object changes.

You can run integration tests locally using a shim. Validate function behavior by confirming the expected result, given specific inputs.

System tests

System tests are more complex tests that validate the behavior of your Cloud Function across multiple GCP components in an isolated test environment.

Deploy your Cloud Function to a test environment and test its functionality by triggering the appropriate events. Validate your function by reading the logs or checking for the desired behavior.

You should isolate your development, testing, and production environments. One way to achieve this is to use a separate GCP project for each step.

You should also assign system test resources globally unique names to prevent concurrent tests from interfering with each other. You can do this by programmatically creating and deleting the required resources before and after the test run.

Example testing scenarios

The scenarios below cover the different ways of triggering Cloud Functions. The structure of a function's tests depends heavily on which GCP resources a function uses. In turn, a function's resource use depends on how that function is triggered.

HTTP-triggered functions

Unlike tests for other types of functions, system and integration tests for HTTP-triggered functions are similar in structure, but most HTTP function unit tests have a different structure.

This overlap between system and integration tests is shown in the following example of an HTTP-triggered function:

Node.js

functions/helloworld/index.js 
const escapeHtml = require('escape-html');

/**
 * HTTP Cloud Function.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */
exports.helloHttp = (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
};

Python

functions/helloworld/main.py 
from flask import escape

def hello_http(request):
    """HTTP Cloud Function.
    Args:
        request (flask.Request): The request object.
        <http://flask.pocoo.org/docs/1.0/api/#flask.Request>
    Returns:
        The response text, or any set of values that can be turned into a
        Response object using `make_response`
        <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>.
    """
    request_json = request.get_json(silent=True)
    request_args = request.args

    if request_json and 'name' in request_json:
        name = request_json['name']
    elif request_args and 'name' in request_args:
        name = request_args['name']
    else:
        name = 'World'
    return 'Hello {}!'.format(escape(name))

Go

functions/helloworld/hello_http.go 
// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"encoding/json"
	"fmt"
	"html"
	"net/http"
)

// HelloHTTP is an HTTP Cloud Function with a request parameter.
func HelloHTTP(w http.ResponseWriter, r *http.Request) {
	var d struct {
		Name string `json:"name"`
	}
	if err := json.NewDecoder(r.Body).Decode(&d); err != nil {
		fmt.Fprint(w, "Hello, World!")
		return
	}
	if d.Name == "" {
		fmt.Fprint(w, "Hello, World!")
		return
	}
	fmt.Fprintf(w, "Hello, %s!", html.EscapeString(d.Name))
}

Unit tests

These tests act as unit tests for the HTTP-triggered function above.

Node.js

Express is mocked using Sinon.
functions/helloworld/test/sample.unit.http.test.js 
const assert = require('assert');
const sinon = require('sinon');
const uuid = require('uuid');

const {helloHttp} = require('..');

it('helloHttp: should print a name', () => {
  // Mock ExpressJS 'req' and 'res' parameters
  const name = uuid.v4();
  const req = {
    body: {
      name: name,
    },
  };
  const res = {send: sinon.stub()};

  // Call tested function
  helloHttp(req, res);

  // Verify behavior of tested function
  assert.ok(res.send.calledOnce);
  assert.deepStrictEqual(res.send.firstCall.args, [`Hello ${name}!`]);
});

it('helloHttp: should print hello world', () => {
  // Mock ExpressJS 'req' and 'res' parameters
  const req = {
    body: {},
  };
  const res = {send: sinon.stub()};

  // Call tested function
  helloHttp(req, res);

  // Verify behavior of tested function
  assert.ok(res.send.calledOnce);
  assert.deepStrictEqual(res.send.firstCall.args, ['Hello World!']);
});

Python

Flask is mocked using unittest.
functions/helloworld/sample_http_test.py 
from unittest.mock import Mock

import main


def test_print_name():
    name = 'test'
    data = {'name': name}
    req = Mock(get_json=Mock(return_value=data), args=data)

    # Call tested function
    assert main.hello_http(req) == 'Hello {}!'.format(name)


def test_print_hello_world():
    data = {}
    req = Mock(get_json=Mock(return_value=data), args=data)

    # Call tested function
    assert main.hello_http(req) == 'Hello World!'

Go

functions/helloworld/hello_http_test.go 
package helloworld

import (
	"io/ioutil"
	"net/http/httptest"
	"strings"
	"testing"
)

func TestHelloHTTP(t *testing.T) {
	tests := []struct {
		body string
		want string
	}{
		{body: `{"name": ""}`, want: "Hello, World!"},
		{body: `{"name": "Gopher"}`, want: "Hello, Gopher!"},
	}

	for _, test := range tests {
		req := httptest.NewRequest("GET", "/", strings.NewReader(test.body))
		req.Header.Add("Content-Type", "application/json")

		rr := httptest.NewRecorder()
		HelloHTTP(rr, req)

		out, err := ioutil.ReadAll(rr.Result().Body)
		if err != nil {
			t.Fatalf("ReadAll: %v", err)
		}
		if got := string(out); got != test.want {
			t.Errorf("HelloHTTP(%q) = %q, want %q", test.body, got, test.want)
		}
	}
}

Use the following command to run the unit tests:

Node.js 

ava test/sample.unit.http.test.js

Python 

pytest sample_http_test.py

Go 

go test -v ./hello_http_test.go

Integration tests

These tests act as integration tests for the function above:

Node.js

functions/helloworld/test/sample.integration.http.test.js 
const assert = require('assert');
const Supertest = require('supertest');
const supertest = Supertest(process.env.BASE_URL);

it('helloHttp: should print a name', async () => {
  await supertest
    .post('/helloHttp')
    .send({name: 'John'})
    .expect(200)
    .expect(response => {
      assert.strictEqual(response.text, 'Hello John!');
    });
});

it('helloHttp: should print hello world', async () => {
  await supertest
    .get('/helloHttp')
    .expect(200)
    .expect(response => {
      assert.strictEqual(response.text, 'Hello World!');
    });
});

To run integration tests for HTTP functions, use the following command:

Node.js 

export BASE_URL=http://localhost:8010/YOUR_GCP_PROJECT_ID/YOUR_GCF_REGION
ava test/sample.integration.http.test.js

where:

  • YOUR_GCP_PROJECT_ID is your GCP project ID.
  • YOUR_GCF_REGION is your Cloud Functions region.
  • BASE_URL is an environment variable that specifies the URL where the function can be reached. Environment variables let you specify values available only in your local test environment. This allows you to avoid hardcoding these values into your code.

System tests

These tests act as system tests for the function above:

Node.js

Note that the system tests are identical to the function's integration tests.
functions/helloworld/test/sample.system.http.test.js 
const assert = require('assert');
const Supertest = require('supertest');
const supertest = Supertest(process.env.BASE_URL);

it('helloHttp: should print a name', async () => {
  await supertest
    .post('/helloHttp')
    .send({name: 'John'})
    .expect(200)
    .expect(response => {
      assert.strictEqual(response.text, 'Hello John!');
    });
});

it('helloHttp: should print hello world', async () => {
  await supertest
    .get('/helloHttp')
    .expect(200)
    .expect(response => {
      assert.strictEqual(response.text, 'Hello World!');
    });
});

Python

functions/helloworld/sample_http_test_system.py 
import os
import uuid

import requests


def test_no_args():
    BASE_URL = os.getenv('BASE_URL')
    assert BASE_URL is not None

    res = requests.get('{}/hello_http'.format(BASE_URL))
    assert res.text == 'Hello, World!'


def test_args():
    BASE_URL = os.getenv('BASE_URL')
    assert BASE_URL is not None

    name = str(uuid.uuid4())
    res = requests.post(
      '{}/hello_http'.format(BASE_URL),
      json={'name': name}
    )
    assert res.text == 'Hello, {}!'.format(name)

Go

functions/helloworld/hello_http_system_test.go 
package helloworld

import (
	"io/ioutil"
	"net/http"
	"net/url"
	"os"
	"strings"
	"testing"
	"time"
)

func TestHelloHTTPSystem(t *testing.T) {
	client := http.Client{
		Timeout: 10 * time.Second,
	}
	urlString := os.Getenv("BASE_URL") + "/HelloHTTP"
	testURL, err := url.Parse(urlString)
	if err != nil {
		t.Fatalf("url.Parse(%q): %v", urlString, err)
	}

	tests := []struct {
		body string
		want string
	}{
		{body: `{"name": ""}`, want: "Hello, World!"},
		{body: `{"name": "Gopher"}`, want: "Hello, Gopher!"},
	}

	for _, test := range tests {
		req := &http.Request{
			Method: http.MethodPost,
			Body:   ioutil.NopCloser(strings.NewReader(test.body)),
			URL:    testURL,
		}
		resp, err := client.Do(req)
		if err != nil {
			t.Fatalf("HelloHTTP http.Get: %v", err)
		}
		body, err := ioutil.ReadAll(resp.Body)
		if err != nil {
			t.Fatalf("HelloHTTP ioutil.ReadAll: %v", err)
		}
		if got := string(body); got != test.want {
			t.Errorf("HelloHTTP(%q) = %q, want %q", test.body, got, test.want)
		}
	}
}

To run system tests for HTTP functions, deploy your functions with the following command:

Node.js 8 

gcloud functions deploy helloHttp --runtime nodejs8

Node.js 10 (Beta) 

gcloud functions deploy helloHttp --runtime nodejs10

Node.js 6 (Deprecated) 

gcloud functions deploy helloHttp --runtime nodejs6

Python 

gcloud functions deploy hello_http --runtime python37

Go 

gcloud functions deploy HelloHTTP --runtime go111

Use the following commands to test your deployed HTTP function:

Node.js

Note that the primary difference between system tests and integration tests for HTTP Cloud Functions is the URL where the function can be reached.

export BASE_URL=https://YOUR_GCF_REGION-YOUR_GCP_PROJECT_ID.cloudfunctions.net/
ava test/sample.system.http.test.js

Python 

export BASE_URL=https://YOUR_GCF_REGION-YOUR_GCP_PROJECT_ID.cloudfunctions.net/
pytest sample_http_test_system.py

Go 

export BASE_URL=https://YOUR_GCF_REGION-YOUR_GCP_PROJECT_ID.cloudfunctions.net/
go test -v ./hello_http_system_test.go

where:

  • YOUR_GCF_REGION is your Cloud Functions region.
  • YOUR_GCP_PROJECT_ID is your GCP project ID.

Pub/Sub-triggered functions

Pub/Sub-triggered function tests are structured differently depending on where the tested function resides.

Here is an example of a Pub/Sub-triggered function:

Node.js 8/10

functions/node8/index.js 
/**
 * Background Cloud Function to be triggered by Pub/Sub.
 * This function is exported by index.js, and executed when
 * the trigger topic receives a message.
 *
 * @param {object} pubSubEvent The event payload.
 * @param {object} context The event metadata.
 */
exports.helloPubSub = (pubSubEvent, context) => {
  const name = pubSubEvent.data
    ? Buffer.from(pubSubEvent.data, 'base64').toString()
    : 'World';

  console.log(`Hello, ${name}!`);
};

Node.js 6 (Deprecated)

functions/helloworld/index.js 
/**
 * Background Cloud Function to be triggered by Pub/Sub.
 * This function is exported by index.js, and executed when
 * the trigger topic receives a message.
 *
 * @param {object} event The Cloud Functions event.
 * @param {function} callback The callback function.
 */
exports.helloPubSub = (event, callback) => {
  const pubsubMessage = event.data;
  const name = pubsubMessage.data
    ? Buffer.from(pubsubMessage.data, 'base64').toString()
    : 'World';

  console.log(`Hello, ${name}!`);

  callback();
};

Python

functions/helloworld/main.py 
def hello_pubsub(data, context):
    """Background Cloud Function to be triggered by Pub/Sub.
    Args:
         data (dict): The dictionary with data specific to this type of event.
         context (google.cloud.functions.Context): The Cloud Functions event
         metadata.
    """
    import base64

    if 'data' in data:
        name = base64.b64decode(data['data']).decode('utf-8')
    else:
        name = 'World'
    print('Hello {}!'.format(name))

Go

functions/helloworld/hello_pubsub.go 
// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"log"
)

// PubSubMessage is the payload of a Pub/Sub event.
type PubSubMessage struct {
	Data []byte `json:"data"`
}

// HelloPubSub consumes a Pub/Sub message.
func HelloPubSub(ctx context.Context, m PubSubMessage) error {
	name := string(m.Data)
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}

Unit tests

These tests act as unit tests for the Pub/Sub-triggered function above:

Node.js 8/10

functions/node8/test/sample.unit.pubsub.test.js 
const assert = require('assert');
const uuid = require('uuid');
const utils = require('@google-cloud/nodejs-repo-tools');

const {helloPubSub} = require('..');

beforeEach(utils.stubConsole);
afterEach(utils.restoreConsole);

it('helloPubSub: should print a name', async () => {
  // Initialize mocks
  const name = uuid.v4();
  const event = {
    data: Buffer.from(name).toString('base64'),
  };

  // Call tested function and verify its behavior
  await helloPubSub(event);
  assert.strictEqual(console.log.calledWith(`Hello, ${name}!`), true);
});

it('helloPubSub: should print hello world', async () => {
  // Initialize mocks
  const event = {};

  // Call tested function and verify its behavior
  await helloPubSub(event);
  assert.strictEqual(console.log.calledWith('Hello, World!'), true);
});

Node.js 6 (Deprecated)

functions/helloworld/test/sample.unit.pubsub.test.js 
const assert = require('assert');
const uuid = require('uuid');
const utils = require('@google-cloud/nodejs-repo-tools');

const helloPubSub = require('..').helloPubSub;

beforeEach(utils.stubConsole);
afterEach(utils.restoreConsole);

it('helloPubSub: should print a name', done => {
  // Initialize mocks
  const name = uuid.v4();
  const event = {
    data: {
      data: Buffer.from(name).toString('base64'),
    },
  };

  // Call tested function and verify its behavior
  helloPubSub(event, () => {
    assert.ok(console.log.calledWith(`Hello, ${name}!`));
    done();
  });
});

it('helloPubSub: should print hello world', done => {
  // Initialize mocks
  const event = {
    data: {},
  };

  // Call tested function and verify its behavior
  helloPubSub(event, () => {
    assert.ok(console.log.calledWith('Hello, World!'));
    done();
  });
});

Python

functions/helloworld/sample_pubsub_test.py 
import base64

import main


def test_print_hello_world(capsys):
    data = {}

    # Call tested function
    main.hello_pubsub(data, None)
    out, err = capsys.readouterr()
    assert out == 'Hello World!\n'


def test_print_name(capsys):
    name = 'test'
    data = {'data': base64.b64encode(name.encode())}

    # Call tested function
    main.hello_pubsub(data, None)
    out, err = capsys.readouterr()
    assert out == 'Hello {}!\n'.format(name)

Go

functions/helloworld/hello_pubsub_test.go 
package helloworld

import (
	"context"
	"io/ioutil"
	"log"
	"os"
	"testing"
)

func TestHelloPubSub(t *testing.T) {
	tests := []struct {
		data string
		want string
	}{
		{want: "Hello, World!\n"},
		{data: "Go", want: "Hello, Go!\n"},
	}
	for _, test := range tests {
		r, w, _ := os.Pipe()
		log.SetOutput(w)
		originalFlags := log.Flags()
		log.SetFlags(log.Flags() &^ (log.Ldate | log.Ltime))

		m := PubSubMessage{
			Data: []byte(test.data),
		}
		HelloPubSub(context.Background(), m)

		w.Close()
		log.SetOutput(os.Stderr)
		log.SetFlags(originalFlags)

		out, err := ioutil.ReadAll(r)
		if err != nil {
			t.Fatalf("ReadAll: %v", err)
		}
		if got := string(out); got != test.want {
			t.Errorf("HelloPubSub(%q) = %q, want %q", test.data, got, test.want)
		}
	}
}

Use the following command to run the unit tests:

Node.js 

ava test/sample.unit.pubsub.test.js

Python 

pytest sample_pubsub_test.py

Go 

go test -v ./hello_pubsub_test.go

Integration tests

These tests act as integration tests for the Pub/Sub-triggered function above:

Node.js

functions/helloworld/test/sample.integration.pubsub.test.js 
const childProcess = require('child_process');
const assert = require('assert');
const uuid = require('uuid');

it('helloPubSub: should print a name', done => {
  const startTime = new Date(Date.now()).toISOString();
  const name = uuid.v4();

  // Mock Pub/Sub call, as the emulator doesn't listen to Pub/Sub topics
  const encodedName = Buffer.from(name).toString('base64');
  const data = JSON.stringify({data: encodedName});
  childProcess.execSync(`functions call helloPubSub --data ${data}`);

  // Check the emulator's logs
  const logs = childProcess
    .execSync(`functions logs read helloPubSub --start-time ${startTime}`)
    .toString();
  assert.strictEqual(logs.includes(`Hello, ${name}!`), true);
  done();
});

it('helloPubSub: should print hello world', done => {
  const startTime = new Date(Date.now()).toISOString();

  // Mock Pub/Sub call, as the emulator doesn't listen to Pub/Sub topics
  childProcess.execSync('functions call helloPubSub --data {}');

  // Check the emulator's logs
  const logs = childProcess
    .execSync(`functions logs read helloPubSub --start-time ${startTime}`)
    .toString();
  assert.strictEqual(logs.includes('Hello, World!'), true);
  done();
});

To run the integration tests for this function, complete the following steps:

Node.js

To run the test, use the following command:

<pre class="lang-sh notranslate prettyprint devsite-click-to-copy">
ava test/sample.integration.pubsub.test.js
</pre>

System tests

These tests act as system tests for this function:

Node.js

functions/helloworld/test/sample.system.pubsub.test.js 
const childProcess = require('child_process');
const assert = require('assert');
const uuid = require('uuid');
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

process.env.FUNCTIONS_TOPIC =
  'projects/grass-clump-479/topics/gcloud-logging-test0165b071-1325-11e9-bc58-d3b6d1def78e';
const topicName = process.env.FUNCTIONS_TOPIC;
const baseCmd = 'gcloud functions';

it('helloPubSub: should print a name', async () => {
  const startTime = new Date(Date.now()).toISOString();
  const name = uuid.v4();

  // Publish to pub/sub topic
  const topic = pubsub.topic(topicName);
  const publisher = topic.publisher();
  await publisher.publish(Buffer.from(name));

  // Wait for logs to become consistent
  await new Promise(resolve => setTimeout(resolve, 15000));

  // Check logs after a delay
  const logs = childProcess
    .execSync(`${baseCmd} logs read helloPubSub --start-time ${startTime}`)
    .toString();
  assert.ok(logs.includes(`Hello, ${name}!`));
});

it('helloPubSub: should print hello world', async () => {
  const startTime = new Date(Date.now()).toISOString();

  // Publish to pub/sub topic
  const topic = pubsub.topic(topicName);
  const publisher = topic.publisher();
  await publisher.publish(Buffer.from(''), {a: 'b'});

  // Wait for logs to become consistent
  await new Promise(resolve => setTimeout(resolve, 15000));

  // Check logs after a delay
  const logs = childProcess
    .execSync(`${baseCmd} logs read helloPubSub --start-time ${startTime}`)
    .toString();
  assert.ok(logs.includes('Hello, World!'));
});

Python

functions/helloworld/sample_pubsub_test_system.py 
from datetime import datetime
from os import getenv
import subprocess
import time
import uuid

from google.cloud import pubsub_v1
import pytest

PROJECT = getenv('GCP_PROJECT')
TOPIC = getenv('TOPIC')

assert PROJECT is not None
assert TOPIC is not None


@pytest.fixture(scope='module')
def publisher_client():
    yield pubsub_v1.PublisherClient()


def test_print_name(publisher_client):
    start_time = datetime.utcnow().isoformat()
    topic_path = publisher_client.topic_path(PROJECT, TOPIC)

    # Publish the message
    name = uuid.uuid4()
    data = str(name).encode('utf-8')
    publisher_client.publish(topic_path, data=data).result()

    # Wait for logs to become consistent
    time.sleep(15)

    # Check logs after a delay
    log_process = subprocess.Popen([
        'gcloud',
        'alpha',
        'functions',
        'logs',
        'read',
        'hello_pubsub',
        '--start-time',
        start_time
    ], stdout=subprocess.PIPE)
    logs = str(log_process.communicate()[0])
    assert 'Hello, {}!'.format(name) in logs

Go

functions/helloworld/hello_pubsub_system_test.go 
package helloworld

import (
	"context"
	"log"
	"os"
	"os/exec"
	"strings"
	"testing"
	"time"

	"cloud.google.com/go/pubsub"
	"github.com/gobuffalo/uuid"
)

func TestHelloPubSubSystem(t *testing.T) {
	ctx := context.Background()

	topicName := os.Getenv("FUNCTIONS_TOPIC")
	projectID := os.Getenv("GCP_PROJECT")

	startTime := time.Now().UTC().Format(time.RFC3339)

	// Create the Pub/Sub client and topic.
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		log.Fatal(err)
	}
	topic := client.Topic(topicName)

	// Publish a message with a random string to verify.
	// We use a random string to make sure the function is logging the correct
	// message for this test invocation.
	u := uuid.Must(uuid.NewV4())
	msg := &pubsub.Message{
		Data: []byte(u.String()),
	}
	topic.Publish(ctx, msg).Get(ctx)

	// Wait for logs to be consistent.
	time.Sleep(20 * time.Second)

	// Check logs after a delay.
	cmd := exec.Command("gcloud", "alpha", "functions", "logs", "read", "HelloPubSub", "--start-time", startTime)
	out, err := cmd.CombinedOutput()
	if err != nil {
		t.Fatalf("exec.Command: %v", err)
	}
	if got := string(out); !strings.Contains(got, u.String()) {
		t.Errorf("HelloPubSub got %q, want to contain %q", got, u.String())
	}
}

To run the system tests:

  1. In your GCP project, select a Cloud Pub/Sub topic to subscribe to. If you provide the name of a Cloud Pub/Sub topic that does not exist, it is created automatically.

  2. Next, deploy your functions using the following command:

    Node.js 8 

    gcloud functions deploy helloPubSub --runtime nodejs8 --trigger-topic YOUR_PUBSUB_TOPIC

    Node.js 10 (Beta) 

    gcloud functions deploy helloPubSub --runtime nodejs10 --trigger-topic YOUR_PUBSUB_TOPIC

    Node.js 6 (Deprecated) 

    gcloud functions deploy helloPubSub --runtime nodejs6 --trigger-topic YOUR_PUBSUB_TOPIC

    Python 

    gcloud functions deploy hello_pubsub --runtime python37 --trigger-topic YOUR_PUBSUB_TOPIC

    Go 

    gcloud functions deploy HelloPubSub --runtime go111 --trigger-topic YOUR_PUBSUB_TOPIC

    where YOUR_PUBSUB_TOPIC is the name of the Cloud Pub/Sub topic you want your functions to subscribe to.

  3. Run the system tests with the following command:

    Node.js 

    export FUNCTIONS_TOPIC=YOUR_PUBSUB_TOPIC
ava test/sample.system.pubsub.test.js

    Python 

    export FUNCTIONS_TOPIC=YOUR_PUBSUB_TOPIC
pytest sample_pubsub_test_system.py

    Go 

    export FUNCTIONS_TOPIC=YOUR_PUBSUB_TOPIC
go test -v ./hello_pubsub_system_test.go

    where YOUR_PUBSUB_TOPIC is the name of the Cloud Pub/Sub topic you want your functions to subscribe to.

Storage-triggered functions

Tests for storage-triggered functions are similar in structure to their Cloud Pub/Sub-triggered counterparts. Like Cloud Pub/Sub-triggered function tests, storage-triggered function tests are structured differently depending on where the tested function is hosted.

Here is an example of a storage-triggered function:

Node.js 8/10

functions/node8/index.js 
/**
 * Background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} data The event payload.
 * @param {object} context The event metadata.
 */
exports.helloGCS = (data, context) => {
  const file = data;
  if (file.resourceState === 'not_exists') {
    console.log(`File ${file.name} deleted.`);
  } else if (file.metageneration === '1') {
    // metageneration attribute is updated on metadata changes.
    // on create value is 1
    console.log(`File ${file.name} uploaded.`);
  } else {
    console.log(`File ${file.name} metadata updated.`);
  }
};

Node.js 6 (Deprecated)

functions/helloworld/index.js 
/**
 * Background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} event The Cloud Functions event.
 * @param {function} callback The callback function.
 */
exports.helloGCS = (event, callback) => {
  const file = event.data;

  if (file.resourceState === 'not_exists') {
    console.log(`File ${file.name} deleted.`);
  } else if (file.metageneration === '1') {
    // metageneration attribute is updated on metadata changes.
    // value is 1 if file was newly created or overwritten
    console.log(`File ${file.name} uploaded.`);
  } else {
    console.log(`File ${file.name} metadata updated.`);
  }

  callback();
};

Python

functions/helloworld/main.py 
def hello_gcs(data, context):
    """Background Cloud Function to be triggered by Cloud Storage.
    Args:
         data (dict): The dictionary with data specific to this type of event.
         context (google.cloud.functions.Context): The Cloud Functions
         event metadata.
    """
    print("File: {}.".format(data['objectId']))

Go

functions/helloworld/hello_cloud_storage.go 
// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"log"
)

// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Bucket         string `json:"bucket"`
	Name           string `json:"name"`
	Metageneration string `json:"metageneration"`
	ResourceState  string `json:"resourceState"`
}

// HelloGCS consumes a GCS event.
func HelloGCS(ctx context.Context, e GCSEvent) error {
	if e.ResourceState == "not_exists" {
		log.Printf("File %v deleted.", e.Name)
		return nil
	}
	if e.Metageneration == "1" {
		// The metageneration attribute is updated on metadata changes.
		// The on create value is 1.
		log.Printf("File %v created.", e.Name)
		return nil
	}
	log.Printf("File %v metadata updated.", e.Name)
	return nil
}

Unit tests

These are the unit tests for the storage-triggered function above:

Node.js 8/10

functions/node8/test/sample.unit.storage.test.js 
const assert = require('assert');
const uuid = require('uuid');
const utils = require('@google-cloud/nodejs-repo-tools');

const {helloGCS} = require('..');

beforeEach(utils.stubConsole);
afterEach(utils.restoreConsole);

it('helloGCS: should print uploaded message', async () => {
  // Initialize mocks
  const filename = uuid.v4();
  const event = {
    name: filename,
    resourceState: 'exists',
    metageneration: '1',
  };

  // Call tested function and verify its behavior
  await helloGCS(event);
  assert.strictEqual(
    console.log.calledWith(`File ${filename} uploaded.`),
    true
  );
});

it('helloGCS: should print metadata updated message', async () => {
  // Initialize mocks
  const filename = uuid.v4();
  const event = {
    name: filename,
    resourceState: 'exists',
    metageneration: '2',
  };

  // Call tested function and verify its behavior
  await helloGCS(event);
  assert.strictEqual(
    console.log.calledWith(`File ${filename} metadata updated.`),
    true
  );
});

it('helloGCS: should print deleted message', async () => {
  // Initialize mocks
  const filename = uuid.v4();
  const event = {
    name: filename,
    resourceState: 'not_exists',
    metageneration: '3',
  };

  // Call tested function and verify its behavior
  await helloGCS(event);
  assert.strictEqual(console.log.calledWith(`File ${filename} deleted.`), true);
});

Node.js 6 (Deprecated)

functions/helloworld/test/sample.unit.storage.test.js 
const assert = require('assert');
const uuid = require('uuid');
const utils = require('@google-cloud/nodejs-repo-tools');

const {helloGCS} = require('..');

beforeEach(utils.stubConsole);
afterEach(utils.restoreConsole);

it('helloGCS: should print uploaded message', done => {
  // Initialize mocks
  const filename = uuid.v4();
  const event = {
    data: {
      name: filename,
      resourceState: 'exists',
      metageneration: '1',
    },
  };

  // Call tested function and verify its behavior
  helloGCS(event, () => {
    assert.ok(console.log.calledWith(`File ${filename} uploaded.`));
    done();
  });
});

it('helloGCS: should print metadata updated message', done => {
  // Initialize mocks
  const filename = uuid.v4();
  const event = {
    data: {
      name: filename,
      resourceState: 'exists',
      metageneration: '2',
    },
  };

  // Call tested function and verify its behavior
  helloGCS(event, () => {
    assert.ok(console.log.calledWith(`File ${filename} metadata updated.`));
    done();
  });
});

it('helloGCS: should print deleted message', done => {
  // Initialize mocks
  const filename = uuid.v4();
  const event = {
    data: {
      name: filename,
      resourceState: 'not_exists',
      metageneration: '3',
    },
  };

  // Call tested function and verify its behavior
  helloGCS(event, () => {
    assert.ok(console.log.calledWith(`File ${filename} deleted.`));
    done();
  });
});

Python

functions/helloworld/sample_storage_test.py 
import main


def test_print(capsys):
    name = 'test'
    data = {'objectId': name}

    # Call tested function
    main.hello_gcs(data, None)
    out, err = capsys.readouterr()
    assert out == 'File: {}.\n'.format(name)

Go

functions/helloworld/hello_cloud_storage_test.go 
package helloworld

import (
	"context"
	"fmt"
	"io/ioutil"
	"log"
	"os"
	"testing"
)

func TestHelloGCS(t *testing.T) {
	name := "hello_gcs.txt"
	tests := []struct {
		resourceState  string
		metageneration string
		want           string
	}{
		{
			resourceState: "not_exists",
			want:          fmt.Sprintf("File %s deleted.\n", name),
		},
		{
			metageneration: "1",
			want:           fmt.Sprintf("File %s created.\n", name),
		},
		{
			want: fmt.Sprintf("File %s metadata updated.\n", name),
		},
	}

	for _, test := range tests {
		r, w, _ := os.Pipe()
		log.SetOutput(w)
		originalFlags := log.Flags()
		log.SetFlags(log.Flags() &^ (log.Ldate | log.Ltime))

		e := GCSEvent{
			Name:           name,
			ResourceState:  test.resourceState,
			Metageneration: test.metageneration,
		}
		HelloGCS(context.Background(), e)

		w.Close()
		log.SetOutput(os.Stderr)
		log.SetFlags(originalFlags)

		out, err := ioutil.ReadAll(r)
		if err != nil {
			t.Fatalf("ReadAll: %v", err)
		}

		if got := string(out); got != test.want {
			t.Errorf("HelloGCS(%+v) = %q, want %q", e, got, test.want)
		}
	}
}

Use the following command to run the unit tests:

Node.js 

ava test/sample.unit.storage.test.js

Python 

pytest sample_storage_test.py

Go 

go test -v ./hello_cloud_storage_test.go

Integration tests

These are the integration tests for the storage-triggered function above:

Node.js

functions/helloworld/test/sample.integration.storage.test.js 
const childProcess = require('child_process');
const assert = require('assert');
const uuid = require('uuid');

it('helloGCS: should print uploaded message', done => {
  const startTime = new Date(Date.now()).toISOString();
  const filename = uuid.v4(); // Use a unique filename to avoid conflicts

  // Mock GCS call, as the emulator doesn't listen to GCS buckets
  const data = JSON.stringify({
    name: filename,
    resourceState: 'exists',
    metageneration: '1',
  });

  childProcess.execSync(`functions-emulator call helloGCS --data '${data}'`);

  // Check the emulator's logs
  const logs = childProcess
    .execSync(`functions-emulator logs read helloGCS --start-time ${startTime}`)
    .toString();
  assert.ok(logs.includes(`File ${filename} uploaded.`));
  done();
});

it('helloGCS: should print metadata updated message', done => {
  const startTime = new Date(Date.now()).toISOString();
  const filename = uuid.v4(); // Use a unique filename to avoid conflicts

  // Mock GCS call, as the emulator doesn't listen to GCS buckets
  const data = JSON.stringify({
    name: filename,
    resourceState: 'exists',
    metageneration: '2',
  });

  childProcess.execSync(`functions-emulator call helloGCS --data '${data}'`);

  // Check the emulator's logs
  const logs = childProcess
    .execSync(`functions-emulator logs read helloGCS --start-time ${startTime}`)
    .toString();
  assert.ok(logs.includes(`File ${filename} metadata updated.`));
  done();
});

it('helloGCS: should print deleted message', done => {
  const startTime = new Date(Date.now()).toISOString();
  const filename = uuid.v4(); // Use a unique filename to avoid conflicts

  // Mock GCS call, as the emulator doesn't listen to GCS buckets
  const data = JSON.stringify({
    name: filename,
    resourceState: 'not_exists',
    metageneration: '3',
  });

  childProcess.execSync(`functions-emulator call helloGCS --data '${data}'`);

  // Check the emulator's logs
  const logs = childProcess
    .execSync(`functions-emulator logs read helloGCS --start-time ${startTime}`)
    .toString();
  assert.ok(logs.includes(`File ${filename} deleted.`));
});

Use the following command to run the integration tests:

Node.js 

ava test/sample.integration.storage.test.js

System tests

These are the system tests for the storage-triggered function above:

Node.js

functions/helloworld/test/sample.system.storage.test.js 
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const uuid = require('uuid');
const assert = require('assert');
const path = require('path');
const childProcess = require('child_process');
const localFileName = 'test.txt';

// Use unique GCS filename to avoid conflicts between concurrent test runs
const gcsFileName = `test-${uuid.v4()}.txt`;

const bucketName = process.env.FUNCTIONS_BUCKET;
const bucket = storage.bucket(bucketName);
const baseCmd = 'gcloud functions';

it('helloGCS: should print uploaded message', async () => {
  const startTime = new Date(Date.now()).toISOString();

  // Upload file
  const filepath = path.join(__dirname, localFileName);
  await bucket.upload(filepath, {
    destination: gcsFileName,
  });

  // Wait for consistency
  await new Promise(resolve => setTimeout(resolve, 15000));

  // Check logs
  const logs = childProcess
    .execSync(`${baseCmd} logs read helloGCS --start-time ${startTime}`)
    .toString();
  assert.ok(logs.includes(`File ${gcsFileName} uploaded`));
});

it('helloGCS: should print metadata updated message', async () => {
  const startTime = new Date(Date.now()).toISOString();

  // Update file metadata
  const file = bucket.file(gcsFileName);
  await file.setMetadata(gcsFileName, {foo: 'bar'});

  // Wait for consistency
  await new Promise(resolve => setTimeout(resolve, 15000));

  // Check logs
  const logs = childProcess
    .execSync(`${baseCmd} logs read helloGCS --start-time ${startTime}`)
    .toString();
  assert.strictEqual(logs.ok(`File ${gcsFileName} metadata updated`));
});

it('helloGCS: should print deleted message', async () => {
  const startTime = new Date(Date.now()).toISOString();

  // Delete file
  bucket.deleteFiles();

  // Wait for consistency
  await new Promise(resolve => setTimeout(resolve, 15000));

  // Check logs
  const logs = childProcess
    .execSync(`${baseCmd} logs read helloGCS --start-time ${startTime}`)
    .toString();
  assert.ok(logs.includes(`File ${gcsFileName} deleted`));
});

Python

functions/helloworld/sample_storage_test_system.py 
from datetime import datetime
from os import getenv, path
import subprocess
import time
import uuid

from google.cloud import storage
import pytest

PROJECT = getenv('GCP_PROJECT')
BUCKET = getenv('BUCKET')

assert PROJECT is not None
assert BUCKET is not None


@pytest.fixture(scope='module')
def storage_client():
    yield storage.Client()


@pytest.fixture(scope='module')
def bucket_object(storage_client):
    bucket_object = storage_client.get_bucket(BUCKET)
    yield bucket_object


@pytest.fixture(scope='module')
def uploaded_file(bucket_object):
    name = 'test-{}.txt'.format(str(uuid.uuid4()))
    blob = bucket_object.blob(name)

    test_dir = path.dirname(path.abspath(__file__))
    blob.upload_from_filename(path.join(test_dir, 'test.txt'))
    yield name
    blob.delete()


def test_hello_gcs(uploaded_file):
    start_time = datetime.utcnow().isoformat()
    time.sleep(10)  # Wait for logs to become consistent

    log_process = subprocess.Popen([
        'gcloud',
        'alpha',
        'functions',
        'logs',
        'read',
        'hello_gcs',
        '--start-time',
        start_time
    ], stdout=subprocess.PIPE)
    logs = str(log_process.communicate()[0])
    assert uploaded_file in logs

Go

functions/helloworld/hello_cloud_storage_system_test.go 
package helloworld

import (
	"context"
	"fmt"
	"os"
	"os/exec"
	"strings"
	"testing"
	"time"

	"cloud.google.com/go/storage"
)

func TestHelloGCSSystem(t *testing.T) {
	ctx := context.Background()
	bucketName := os.Getenv("BUCKET_NAME")

	client, err := storage.NewClient(ctx)
	if err != nil {
		t.Fatalf("storage.NewClient: %v", err)
	}

	// Create a file.
	startTime := time.Now().UTC().Format(time.RFC3339)
	oh := client.Bucket(bucketName).Object("TestHelloGCSSystem")
	w := oh.NewWriter(ctx)
	fmt.Fprintf(w, "Content of the file")
	w.Close()

	// Wait for logs to be consistent.
	time.Sleep(20 * time.Second)

	// Check logs.
	want := "created"
	if got := readLogs(t, startTime); !strings.Contains(got, want) {
		t.Errorf("HelloGCS logged %q, want to contain %q", got, want)
	}

	// Modify the file.
	startTime = time.Now().UTC().Format(time.RFC3339)
	_, err = oh.Update(ctx, storage.ObjectAttrsToUpdate{
		Metadata: map[string]string{"Content-Type": "text/html"},
	})
	if err != nil {
		t.Errorf("Update: %v", err)
	}

	// Wait for logs to be consistent.
	time.Sleep(20 * time.Second)

	// Check logs.
	want = "updated"
	if got := readLogs(t, startTime); !strings.Contains(got, want) {
		t.Errorf("HelloGCS logged %q, want to contain %q", got, want)
	}

	// Delete the file.
	startTime = time.Now().UTC().Format(time.RFC3339)
	if err := oh.Delete(ctx); err != nil {
		t.Errorf("Delete: %v", err)
	}

	// Wait for logs to be consistent.
	time.Sleep(20 * time.Second)

	// Check logs.
	want = "deleted"
	if got := readLogs(t, startTime); !strings.Contains(got, want) {
		t.Errorf("HelloGCS logged %q, want to contain %q", got, want)
	}
}

func readLogs(t *testing.T, startTime string) string {
	t.Helper()
	cmd := exec.Command("gcloud", "alpha", "functions", "logs", "read", "HelloGCS", "--start-time", startTime)
	got, err := cmd.CombinedOutput()
	if err != nil {
		t.Fatalf("exec.Command: %v", err)
	}
	return string(got)
}

Use the following command to deploy your function:

Node.js 8 

gcloud functions deploy helloGCS --runtime nodejs8 --trigger-bucket YOUR_GCS_BUCKET_NAME

Node.js 10 (Beta) 

gcloud functions deploy helloGCS --runtime nodejs10 --trigger-bucket YOUR_GCS_BUCKET_NAME

Node.js 6 (Deprecated) 

gcloud functions deploy helloGCS --runtime nodejs6 --trigger-bucket YOUR_GCS_BUCKET_NAME

Python 

gcloud functions deploy hello_gcs --runtime python37 --trigger-bucket YOUR_GCS_BUCKET_NAME

Go 

gcloud functions deploy HelloGCS --runtime go111 --trigger-bucket YOUR_GCS_BUCKET_NAME

where YOUR_GCS_BUCKET_NAME is the Cloud Storage bucket you want to monitor. Note that this must reference a bucket that exists in the same GCP project that the function is deployed to.

Use the following commands to run the system tests:

Node.js 

export BUCKET_NAME=YOUR_GCS_BUCKET_NAME
ava test/sample.system.storage.test.js

Python 

export BUCKET_NAME=YOUR_GCS_BUCKET_NAME
pytest sample_storage_test_system.py

Go 

export BUCKET_NAME=YOUR_GCS_BUCKET_NAME
go test -v ./hello_cloud_storage_system_test.go

Continuous testing and deployment

As you develop your function, you can run unit tests, integration tests, and system tests to ensure that your functions work both locally and in a test environment on GCP.

Once you finish developing locally, you can configure a continuous integration and deployment (CI/CD) platform such as Cloud Build to run your existing Cloud Functions tests on an ongoing basis. Continuous testing helps ensure that your code continues to work as intended and that your dependencies remain up-to-date. As Cloud Functions are not updated automatically, you can also configure continuous integration platforms (including Cloud Build) to automatically test and redeploy your functions from a source repository such as GitHub, Bitbucket, or Cloud Source Repositories.

Follow the instructions in the Automating Builds using Build Triggers guide using the cloudbuild.yaml build config file below to configure Cloud Build to automatically test and deploy your function.

Node.js

functions/ci_cd/cloudbuild.yaml 
steps:
- name: 'gcr.io/cloud-builders/yarn'
  args: ['install']
  dir: 'functions/autodeploy'
- name: 'gcr.io/cloud-builders/npm'
  args: ['test']
  dir: 'functions/autodeploy'
- name: 'gcr.io/cloud-builders/gcloud'
  args: ['functions', 'deploy', '[YOUR_DEPLOYED_FUNCTION_NAME]', '[YOUR_FUNCTION_TRIGGER]', '--runtime', '[YOUR_RUNTIME]', '--entry-point', '[YOUR_FUNCTION_NAME_IN_CODE]']
  dir: 'functions/autodeploy'

Replace

  • [YOUR_FUNCTION_NAME] with the name of your Cloud Functions to be used in the Google Cloud Platform Console, Cloud SDK, and URL.
  • [YOUR_FUNCTION_TRIGGER] with the appropriate trigger value such as --trigger-http.
  • [YOUR_RUNTIME] with the runtime identifier such as nodejs10.
  • [YOUR_FUNCTION_NAME_IN_CODE] with the function name as it appears in code. --entry-point is only needed if this value is different than [YOUR_FUNCTION_NAME].

If Cloud Build doesn't suit your needs, see this list of continuous integration platforms.

Granting permissions to run builds and deployments

If you are using Cloud Build, you need to grant permissions to the Cloud Build service account.

For example:

  • To deploy Cloud Functions, you might want to assign the Cloud Functions Developer role to the Cloud Build service account (PROJECT_NUMBER@cloudbuild.gserviceaccount.com).
  • If you use the Cloud Functions Developer role, you also need to grant the Cloud Functions Runtime service account (PROJECT_ID@appspot.gserviceaccount.com) the IAM Service Account User role.
Was this page helpful? Let us know how we did:

Send feedback about...

This page
Documentation feedback
Cloud Functions Documentation
Product feedback