Run Functions Locally

You can run functions locally to test them before deploying to production. To run functions locally, use either:

  • The Cloud Functions shell. This tool emulates all types of function triggers, and provides an interactive shell for invoking the functions with test data.
  • The Firebase CLI's firebase serve command. This tool emulates HTTPS functions, providing a URL to trigger the local function.

For both tools, code changes you make during an active session are automatically reloaded by the emulator.

Use Firebase serve for HTTPS Functions

To use this feature, firebase-tools must have minimum version 3.8.0, and firebase-functions SDK must have minimum version 0.5.7. To update both, run the following commands in the functions/ directory for your project:

npm install --save firebase-functions@latest firebase-admin
npm install -g firebase-tools

To run functions locally, use firebase serve:

firebase serve --only functions # to only emulate functions
firebase serve --only functions,hosting # to emulate both functions and hosting

This command outputs a URL for your Firebase hosting content, and a URL for each HTTPS function. If you are using functions to dynamically generate content for Firebase hosting, then this uses your local functions as proxies for hosting.

Use the 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 and PubSub triggers, and optional for all other function types. Also, the optional options parameter is valid only for Realtime Database 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);

Install and configure the Cloud Functions shell

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 are not using custom functions configuration variables, run the shell with the following command:

firebase experimental:functions:shell

If you're using custom functions configuration variables, first run the command to get your custom config (run this within the functions directory), and then run the shell:

firebase functions:config:get > .runtimeconfig.json
firebase experimental: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 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 administrative 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', {auth: {admin: false}}
# to mock end user
myDatabaseFunction('data', {auth: {variable: {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 options, the shell provides the params option to use in mocking 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:'bar'},
    // 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, Auth, and Crashlytics functions

For Storage, Auth, and Crashlytics 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.

Logging

Both tools, firebase serve and the Cloud Functions shell, stream logs from your functions to the terminal window where they run. They displays all output from console.log(), console.info(), console.error(), and console.warn() statements inside your functions.

Send feedback about...

Need help? Visit our support page.