Skip to content

Debug and test function injection

This SDK functionality is in Beta.

While developing an integration that injects serverless functions, you can test it locally to check if it works as expected.

You can only test functions after you inject them into a site

Since functions are created within your integration, the only way to test them is by adding your integration and injecting the functions into a test site first. Once you run that test site, you can invoke functions while the site runs, as documented below. There is no way to test them in isolation.

Test your integration

To test your integration, you need to prepare a test site and then run netlify dev or netlify build to inject the functions.

Prepare a test site

  1. Have a test site repository and your integration repository on your local machine.
  2. Create a test site on Netlify.
  3. Install the Netlify CLI with npm install netlify-cli -g.
  4. Make sure your test site is a git repository by running git init in the root of your test site.
  5. Log in to your Netlify account with netlify login.
  6. Link your local test site to the test site you created on Netlify by running netlify link.
  7. Create a netlify.toml file in the root of your test site with the following configuration. Make sure to update the name to match your integration’s slug and the path to specify the location of the integration on your local machine.
# Set the integration "name" to your integration's slug.
name = "my-integration"
# Set the "path" as the path from your test site to your integration's build folder.
path = "../path/to/integration/repository"
# The following forces the integration to be used when building the test site.
force_run_in_build = true

Test injection and invocations locally

Now that your test site is ready, you can test your integration and the functions locally. To do so, run the following command for your test site in your terminal:

netlify dev

Netlify will inject the functions from your integration into the site during the onPreDev build event and then start a development environment that executes functions on local requests.

You can then invoke and debug the functions on your test site by making a request to the appropriate site path for each function. Learn more about testing and debugging serverless functions locally.

To invoke background functions, make a POST request to the functions path once your site is running.

Scheduled functions won’t run on a schedule locally but you can invoke them immediately for testing. Learn more about developing and debugging scheduled functions.

If you only want to test the injection step, you can run the following in your terminal:

netlify build --context=dev

This runs a build of your test site. Netlify will inject the functions from your integration into the site during the onPreBuild build event.

When you make changes to your integration’s functions, you can check the results in your terminal by re-running the build command. Any console.log statements will show in the terminal.

Note that if your integration includes custom build event handlers that run onPreBuild or onPreDev, Netlify injects the functions before your build event handlers run.