@e965/newrelic-browser-agent
Advanced tools
Tests for the New Relic JavaScript agent
The New Relic Browser agent instruments your website and provides observability into the performance and behavior of your application.
To get started using the Browser agent in your own code, our Docs site is the best place to look:
We use webpack to automate builds of the agent. To build:
npm ci
npm run cdn:build:local
Build artifacts are placed in the /build directory.
To automatically rebuild the agent on each change:
npm run cdn:watch
The Browser agent is loaded onto a web page in two parts. To install a version of the agent build locally:
/build directory via a local HTTP server (see instructions above to build the agent).<head> tag of your webpage.<!-- Browser agent configuration -->
<script type="text/javascript">
window.NREUM || (NREUM = {});
NREUM.info = {
licenseKey: "example",
applicationID: 123,
};
</script>
<!-- Browser agent loader script -->
<script src="http://localhost:8080/nr-loader-spa.js"></script>
NOTE: Your browser might cache JS scripts, which means you may not see your changes when the agent files are re-built. To turn off caching in Chrome, open DevTools and check the Disable cache checkbox.
The prebuilt test server can serve the locally built agent files as noted under Debugging Tests below. To use this server, run the npm run test-server command.
The Browser agent uses a JSON configuration to set license key and application ID.
You can find the licenseKey and applicationID in the New Relic UI's Browser Application Settings page (one.newrelic.com > Browser > (select an app) > Settings > Application settings.)
Pick an agent type and update the following files from the table below:
| Agent type | loader filename |
|---|---|
| Lite | nr-loader-rum.min.js |
| Pro | nr-loader-full.min.js |
| Pro + SPA | nr-loader-spa.min.js |
The agent loader will automatically import any necessary chunks of code later on the page after being successfully initialized wiht configurations.
See the sections below for details about local and PR testing.
The Browser agent uses a tool called the JavaScript Integration test Loader (jil) to run
tests (located in /tools/jil).
Before running tests locally, be sure to install and build from the root directory to ensure all dependencies are loaded and the application is properly built.
npm install
npm run build:all
To run all tests on a specific browser/platform, you can either run on Saucelabs or point the testing framework to your own Selenium server.
To run tests on Saucelabs, you will need your own Saucelabs account. Export your Saucelabs username and access key in these environment variables - JIL_SAUCE_LABS_USERNAME, JIL_SAUCE_LABS_ACCESS_KEY. After that you can use the following command to run tests on a specific browser. Note that the browser/platform needs to be defined in this matrix file.
Here is an example of running all tests on the latest version of Chrome.
npm run test -- -s -b chrome@latest
Here is an example of using your own Selenium server:
npm run test -- -b chrome@latest --selenium-server=localhost:4444
Important Notes:
jil does not handle building the agent automatically;
either run npm run build:all after each change, or use npm run watch to automatically rebuild on each change.npm run test you must separate your arguments from the npm script using an empty -- parameter as was exemplified above.To run a single test in isolation, pass the path to jil:
npm run test -- tests/functional/api.test.js
To debug a unit test (/tests/browser) or the asset under test in a unit or functional test (/tests/assets), run the command below:
npm run test-server
Running this command starts a server, available at http://localhost:3333, with a list of all available unit tests and test HTML pages with the Browser agent installed. Select a unit test from the list to run the test itself in your browser, or select an asset from the list to debug.
Important: When running jil-server be sure to tell HTML files which Browser agent type you want by adding a ?loader=spa to the querystring. Here's an example:
http://localhost:3333/tests/assets/spa/fetch.html?loader=spa
| Agent type | querystring name |
|---|---|
| Lite | rum |
| Pro (default) | full |
| Pro + SPA | spa |
When you open a PR, the agent's functional and unit test suite will be run on the latest version of Chrome, Firefox and Safari to quickly validate the new code. If that passes, the PR will run functional and unit tests again against the full matrix of browsers and browser versions that are required to pass before approving a PR.
New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads here:
https://discuss.newrelic.com/c/full-stack-observability/browser
We encourage your contributions to improve the Browser agent! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at opensource@newrelic.com.
For more details on how best to contribute, see CONTRIBUTING.md
A note about vulnerabilities
As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.
If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.
If you would like to contribute to this project, review these guidelines.
To all contributors, we thank you! Without your contribution, this project would not be what it is today. We also host a community project page dedicated to the Browser agent.
The Browser agent is licensed under the Apache 2.0 License.
The Browser agent also uses source code from third-party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the third-party notices document.
FAQs
Tests for the New Relic JavaScript agent
We found that @e965/newrelic-browser-agent demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.