The Cloud Functions shell provides an interactive shell for invoking
functions with test data. The shell supports all trigger types.
Set up admin credentials (optional)
If you want your functions tests to interact with Google APIs or other Firebase
APIs via the
Firebase Admin SDK
, you may need to set up
admin credentials.
- Cloud Firestore and Realtime Database triggers already have sufficient credentials, and do
not
require additional setup.
- All other APIs, including Firebase APIs such as Authentication and FCM or Google APIs such as Cloud Translation or Cloud Speech, require the setup steps described in this section. This applies whether you're using the Cloud Functions shell or
firebase emulators:start
.
To set up admin credentials for emulated functions:
- Open the
Service Accounts pane
of the Google Cloud console.
- Make sure that
App Engine default service account
is selected, and use
the options menu at right to select
Create key
.
- When prompted, select
JSON
for the key type, and click
Create
.
Set your Google default credentials to point to the downloaded key:
Unix
export GOOGLE_APPLICATION_CREDENTIALS="path/to/key.json"
firebase functions:shell
Windows
set GOOGLE_APPLICATION_CREDENTIALS=path\to\key.json
firebase functions:shell
After completing these steps, your functions tests can access Firebase and
Google APIs using the
Admin SDK
. For example, when testing
an Authentication trigger, the emulated function could call
admin.auth().getUserByEmail(email)
.
Serve functions using a Cloud Functions shell
The Cloud Functions shell emulates all types of function triggers with an
interactive shell for invoking the functions with test data. Options vary
by function type, but the basic usage format is:
myFunctionName(data, options)
The
data
parameter is required for Realtime Database, Cloud Firestore,
and PubSub triggers, and optional for all other function types.
Also, the optional
options
parameter is valid only for Realtime Database
and Cloud Firestore functions.
Optionally, you can load test data from a local
file by saving the file as a variable and invoking a function with it:
var data = require('./path/to/testData.json');
myFunction(data);
To use this feature,
firebase-tools
must have minimum version 3.11.0, and
firebase-functions
SDK must have minimum version 0.6.2. To update both,
run the following commands in the
functions/
directory for your project:
npm install --save firebase-functions@latest
npm install -g firebase-tools
If you're using custom functions configuration variables, first run the
command to get your custom config (run this within the
functions
directory)
in your local environment:
firebase functions:config:get > .runtimeconfig.json
# If using Windows PowerShell, replace the above with:
# firebase functions:config:get | ac .runtimeconfig.json
Finally, run the shell with the following command:
firebase functions:shell
Invoke HTTPS functions
For invoking HTTPS functions in the shell, usage is the same as the
request
NPM module, but replace
request
with the name of the function you want to emulate. For example:
# invoke
myHttpsFunction()
myHttpsFunction.get()
myHttpsFunction.post()
# invoke at sub-path
myHttpsFunction('/path')
myHttpsFunction.get('/path')
myHttpsFunction.post('/path')
# send POST request with form data
myHttpsFunction.post('/path').form( {foo: 'bar' })
Invoke HTTPS Callable functions
When invoking HTTPS Callable functions locally, you'll need to provide appropriate test data.
# invoke
myCallableFunction('test data')
myCallableFunction({'foo': 'bar'})
Optionally, you may pass in a
Firebase-Instance-ID-token
as the second parameter. This must be a string.
# invoke with FCM registration token
myCallableFunction('test data', {instanceIdToken: 'sample token'})
Emulation of
context.auth
is currently unavailable.
Invoke Realtime Database functions
When running Realtime Database functions locally, you'll need to provide
appropriate test data. This generally means providing new test data for
onCreate
operations, old/removed data for
onDelete
operations, and both for
onUpdate
or
onWrite
functions:
# invoke onCreate function
myDatabaseFunction('new_data')
# invoke onDelete function
myDatabaseFunction('old_data')
# invoke onUpdate or onWrite function
myDatabaseFunction({before: 'old_data', after: 'new_data' })
In addition to the
before/after
options, the shell provides the
params
option to use in mocking wildcards in a path:
# mock wildcards in path, for example: if the path was input/{group}/{id}
myDatabaseFunction('data', {params: {group: 'a', id: 123}})
By default, the shell runs Realtime Database functions with admin (service account)
privileges. Use the
auth
option to instead run functions as a particular
end user, or as an unauthenticated user:
# to mock unauthenticated user
myDatabaseFunction('data', {authMode: 'USER'})
# to mock end user
myDatabaseFunction('data', {auth: {uid: 'abcd'}})
Invoke Firestore functions
When running Firestore functions locally, you'll need to provide
appropriate test data. This generally means providing new test data for
onCreate
operations, old/removed data for
onDelete
operations, and both for
onUpdate
or
onWrite
functions. Note that Firestore data has to be
key-value pairs; see
Supported Data Types
.
# invoke onCreate function
myFirestoreFunction({foo: ‘new’})
# invoke onDelete function
myFirestoreFunction({foo: ‘old’})
# invoke onUpdate or onWrite function
myFirestoreFunction({before: {foo: ‘old’}, after: {foo: ‘new’} })
In addition to the
before/after
fields of the
data
object,
you can use the
params
fields on the
options
object to mock
wildcards in a document name:
# mock wildcards in document name, for example: if the name was input/{group}/{id}
myFirestoreFunction({foo: ‘new’}, {params: {group: 'a', id: 123}})
The shell always runs Firestore functions with administrative privileges, which
means it mocks a create/update/delete event as if it were done by an
administrative user.
Invoke PubSub functions
For PubSub functions, insert your message payload in a
Buffer
instance and
add optionally data attributes as shown:
// invokes a function with the JSON message { hello: 'world' } and attributes { foo: 'bar' }
myPubsubFunction({data: new Buffer('{"hello":"world"}'), attributes: {foo: 'bar'}})
Invoke Analytics functions
You can invoke an Analytics function without any data by
running
myAnalyticsFunction()
in the shell.
To run the function with test data, it is recommended to define a variable for
the specific event data fields that your function needs:
var data = {
eventDim: [{
// populates event.data.params
params: {foo: {stringValue: 'bar'} },
// Also valid:
// {intValue: '10'}, {floatValue: '1.0'}, {doubleValue: '1.0'}
// populates event.data.name
name: 'event_name',
// populates event.data.logTime, specify in microseconds
timestampMicros: Date.now() * 1000,
// populates event.data.previousLogTime, specify in microseconds
previousTimestampMicros: Date.now() * 1000,
// populates event.data.reportingDate, specify in 'YYYYMMDD' format
date: '20170930',
// populates event.data.valueInUSD
valueInUsd: 230
}],
userDim: userDim
};
myAnalyticsFunction(data);
Invoke Storage and Auth functions
For Storage and Auth functions, invoke the local function with the
test data that you’d like to see inside of the function. Your test data must
follow the corresponding data formats:
Specify only the fields that your code depends on, or none at all if you only
want to run the function.