Skip to content
Netlify SDK DocsNetlify SDK Docs1.13.2

Debug and test a build event handler

While developing your build event handler, you can test it locally to check if it works as expected.

Reach out to test end-to-end

Currently, you can test your build event handler locally only. You can’t test it on a live environment yet. If you intend to publish your integration and want to test it on a live environment, reach out through our technology partner program and we will work with you to test and publish your integration.

Prepare your test site

To get ready to test your build event handler locally, do the following:

  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. Log in to your Netlify account with netlify login.

  5. Link your local test site to the test site you created on Netlify by running netlify link.

  6. Create a netlify.toml file in the root of your test site with the following configuration:

    # netlify.toml

# Set the integraton "name" to your integration's slug.
[[integrations]]
	name = "my-integration"

[integrations.dev]
   # 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

You don't have to build your build event handler yet

Normally, you have to build your build event handler to compile the code to the .ntli folder. But, you can skip this step when testing locally. The netlify build command you run while testing, as described below, automatically builds your build event handler in addition to building the test site.

Test locally on your test site

Now that your test site is ready, you can test your integration’s build event handler locally. To do so, run the following command for your test site in your terminal:

netlify build --context=dev

This runs a build of your test site while using your integration’s build event handler. You can now make changes to your integration’s build event handler and check the results in your terminal whenever you run the command above. Any console.log statements will show in the local build log.