Test an Add-on

Apps Script allows developers to test scripts in development as add-ons. This can be used to:

  • Verify that an add-on written in a standalone script functions as intended when applied to a Sheet, Doc or Form.
  • Verify that the add-on installation flow works as intended, particularly for different initial authorization lifecycle states (installed, enabled, or both).
  • Verify that the add-on functions as intended when acting on a particular Sheet, Doc or Form.
  • Test and compare the current and previous versions of the add-on.

Create a test configuration

A test configuration is the combination of an add-on and a test document. Once you have a script version developed and would like to test it as an add-on, follow these steps:

  1. If you do not have one already, create a Sheet, Doc or Form to test the add-on with. If desired, format and fill the doc with data that the add-on will be operating on.
  2. Open the script project containing your add-on in the script editor.
  3. (Optional) You may wish to save a version of your project by selecting File > Manage versions, then Save New Version. Close the Manage Versions dialog.
  4. Select Publish > Test as add-on.
  5. In the Select version box, choose a code version or select "Test with latest code".
  6. In the Installation Config box, select the initial authorization state for the test.
  7. Click the Select Doc button. This will bring up a file select dialog. Find the test Sheet, Doc or Form you want to test the add-on on, click it, and then click Select to close the dialog.
  8. Click Save to save the test configuration.

All currently saved test configurations will appear in the Test as add-on dialog. This allows you to revisit the same test configuration later on.

Run a test configuration

If you have one or more saved test configurations, you can run one of them by following these steps:

  1. Open the script project containing your add-on in the script editor.
  2. Select Publish > Test as add-on.
  3. Under Execute Saved Test, find the test to execute and select it. Click Test.

At this point the Sheet, Doc or Form specified in the test configuration will open in a new tab (this document view is referred to as the "add-on preview document"). The add-on will be in the authorization state specified in test configuration. You can now verify that the add-on functions as intended for the test document by interacting with its menu and UI elements.

Testing details

There are a number of things to keep in mind while testing add-ons:

  • Installable triggers are currently not supported when testing. Functionality that depends on installable triggers will not be testable.
  • While running a test configuration set to "Test with latest code," you can see changes saved to the add-on script by refreshing the add-on preview document.
  • The add-on preview document has a URL that can be shared with editors of the original test document. In this way, you can more easily collaborate with others while testing and developing.
  • If your add-on uses the Properties service, properties will persist and remain available the next time the test configuration is run.
  • In addition, any test configuration that uses the same combination of add-on and test document will have access to the same property information. For example, if you create two test configurations, the properties saved while running the first will be available while running the second and vice versa, but only if the configurations use the same script and test document.
  • If you run a test configuration, you may be prompted for authorization if you have not run the script before. Be aware that authorizing a script while testing also authorizes the script outside of testing.

Delete a test configuration

If you have one or more saved test configurations, you can delete one of them by following these steps:

  1. Open the script project containing your add-on in the script editor.
  2. Select Publish > Test as add-on.
  3. Under Execute Saved Test, find the test to execute and select it. Click Delete.

Send feedback about...

Apps Script
Apps Script