Launch Extension Sandbox
Launch, by Adobe, is a next-generation tag management solution enabling simplified deployment of marketing technologies. For more information regarding Launch, please visit our product website.
This project provides a sandbox in which you can manually test your Launch extension. You can test both (1) your views that will eventually appear in the Launch application and (2) your library logic that will eventually run on the user's website.
For more information about developing an extension for Launch, please visit our extension development guide.
Running the Sandbox
Before running the sandbox, you must first have Node.js installed on your computer. Your npm version (npm comes bundled with Node.js) will need to be at least 5.2.0. You can check the installed version by running the following command from a command line:
Once Node.js is installed, run the sandbox by executing the following command from the command line within your project's directory:
A server will be started at http://localhost:3000 (HTTP) and https://localhost:4000 (HTTPS). If you navigate to one of addresses in your browser (you may have to accept a security certificate if you use the HTTPS server), you will see the View Sandbox which allows you to test your views. You'll need to have previously created a view in your extension for it to show up in the sandbox. You can switch between views you would like to test using the controls toward the top of the page.
You may also click on the "Go to library sandbox" button at the top-right of the page to navigate to the library sandbox where you can test your library logic. See Configuring the Sandbox for how to configure the library sandbox for proper testing.
Once this is in place, you may then run the sandbox by executing the command
npm run sandbox from the command line.
Configuring the Sandbox
Web Extensions can also test the library logic inside the sandbox. To configure the Library Sandbox portion, execute the following command from the command line within your project's directory:
npx @adobe/reactor-sandbox init
This will generate a directory within your project named
.sandbox that contains two files you may edit to configure the sandbox:
container.jsWhen Launch publishes a library, it consists of two parts: (1) a data structure that stores information about saved rules, data elements, and extension configuration and (2) an engine to operate on such a data structure.
container.jsis the data structure (not the engine) that you may modify to simulate saved rules, data elements, and extension configuration. This template will be used to produce a complete
container.js, but if you need further help, please let the Launch team know and we can help you out.
libSandbox.htmlincludes some simple HTML along with script tags to load a complete
container.jsand the Turbine engine.
libSandbox.htmlcan be modified to manually test whatever you would like. For example, if you'd like to test that your brand new "focus" event type is working as desired, you can add a text input to the
libSandbox.htmlto ensure your dummy rule fires when a form element receives focus.
Mobile extensions don't have a Library Sandbox portion. Running
npx @adobe/reactor-sandbox init from inside a mobile extension, will show an error.
You are welcome to commit
.sandbox to your version control repository.
Installing as a Dependency
If you find yourself using the the sandbox tool frequently, you may wish to install it as a dependency in your project. This will allow the sandbox tool to run more quickly and provide more control over when you upgrade to newer versions of the sandbox.
If you do not yet have a
package.json in your project's directory, you will need to generate one by running the following command from the command line within your project's directory:
You will need to provide the information requested on the screen. The values you provide are not particularly important and will not affect how your extension operates. After this process is complete, you should have a file called
package.json inside your directory.
Once you have a
package.json, you can install the sandbox as a dependency by running the following command from the command line within your project's directory:
npm i -D @adobe/reactor-sandbox
At this point, you can continue running the sandbox as outlined above.
Advanced Integration with Node Scripts
For advanced users who need greater control of the sandbox from node-based build tools, you also have the option of importing the sandbox tool into your scripts and controlling it programmatically.
After installing the sandbox as a dependency, you may use it from your node scripts as follows:
const sandbox = ;sandbox;
The sandbox module provides the following methods:
run - Runs the sandbox. A promise will be returned that will be resolved once the server is ready.
init - Initializes sandbox configuration files. A promise will be returned that will be resolved once the files have been generated.
Using the Sandbox for Automated Testing
While the sandbox is primarily intended for manually testing an extension, it can also come in handy for automated tests. If you would like to test your extension's user interface using an end-to-end testing tool like TestCafe or Cypress, the view sandbox provides the ability to do so.
Once the sandbox has been started and the view sandbox displayed in a browser, a global method named
loadExtensionView is exposed and can be used to load an extension view programmatically as follows:
This will load the extension view into the iframe in the view sandbox and will then call the
init method that your extension has registered with the extension bridge. The
loadExtensionView method supports the following options:
viewPath(required) The view path to the extension view you wish to load. It must match the
viewPathproperty specified for the view in your extension's
infoobject that will be passed to the
initmethod your extension has registered with the extension bridge.
openCodeEditor(optional) A mock function that will be called when your extension calls
openRegexTester(optional) A mock function that will be called when your extension calls
openDataElementSelector(optional) A mock function that will be called when your extension calls
loadExtensionView method will return a promise that, once the view is loaded and initialized, will be resolved with an object containing the following methods:
initCalling this method will call the
initmethod your extension has registered with the extension bridge. It returns a promise that will be resolved once the extension view has handled the
getSettingsCalling this method will call the
getSettingsmethod your extension has registered with the extension bridge. It returns a promise that will be resolved with the settings returned from your extension's
validateCalling this method will call the
validatemethod your extension has registered with the extension bridge. It returns a promise that will be resolved with the validation result boolean returned from your extension's
As an example, I might want to load an extension view, use a testing tool to mimic user behavior in the extension view, then retrieve the settings and assert that they are as expected. This might look as follows:
// Load the extension view.const extensionView = await window;// At this point, use the testing tool to mimic user behavior// within the extension view.// Retrieve settings.const settings = await extensionView;// Assert that settings are as expected.;
Contributions are welcomed! Read the Contributing Guide for more information.
To get started:
- Install node.js.
- Clone the repository.
- After navigating into the project directory, install project dependencies by running
To manually test your changes, first run the following command from the sandbox tool directory:
Then, in a directory containing an extension (any extension you would like to use for testing), run the following command:
Npx will execute the sandbox tool using your locally linked code rather than the code published on the public npm repository.
To ensure your code meets our linting standards, run the following command:
npm run lint
This project is licensed under the Apache V2 License. See LICENSE for more information.