Specify NPM dependencies

Learn how to run your tests that need third-party or private npm packages.

Though your package.json file might contain many third-party npm packages, not all of these are required for you to successfully run your Cypress tests on BrowserStack.

In this guide, you will learn:

1. Why you need to specify npm packages?
2. How to specify required npm dependencies?
3. How to specify private npm package dependencies?
4. How BrowserStack manages your npm dependency caching?

Why npm dependencies must be specified?

Your Cypress tests are uploaded to BrowserStack and are further run from the BrowserStack machines. Typically, all external npm packages that your tests need to run are specified in the package.json file under the devDependencies section. For your Cypress tests to run on BrowserStack, we use the browserstack.json file and read your dependencies from this file. The package.json is not used by BrowserStack to identify dependencies. You need to set your npm dependencies in the browserstack.json file because:

• The package.json file might contain several devDependencies many of which are not essential for running your tests. For example, the eslint package.
• Installing npm packages in BrowserStack machines is a time intensive task. By installing non-essential packages, we would increase your build time, which can be avoided by skipping such packages.

Based on these benefits, use the information in the following sections to understand which npm packages must be specified in the browserstack.json.

Specify public npm package dependencies

You can use the following keys in the run_settings section under browserstack.json to specify the npm packages and any options that the packages might need for your tests to run successfully.

For Example:

{
  "run_settings": {
    ...
    "npm_dependencies": {
      "npm-package-you-need-to-run-tests-1": "^1.2.1",
      "npm-package-you-need-to-run-tests-2": "^7.1.6-beta.13",
    },
    "package_config_options": {
      "npm-package-you-need-to-run-tests-1_options": {
        "option1": true,
        "option2": "some-value"
      }
    }
  }
}

Specify private npm package dependencies

If your dependencies include privately or internally-hosted npm packages, you can resolve them by adding a .npmrc file as part of your project, with authentication, if required. For such cases, the following two scenarios exist:

• Your registry URL is publicly resolvable
• Your registry URL is only available to your private network

Registry URL is publicly resolvable

Complete the following steps to ensure that your tests run seamlessly on BrowserStack:

1. Specify the private npm package dependency in your browserstack.json file:
   
   browserstack.json

   {
     "run_settings": {
       ...
       "npm_dependencies": {
          "your-private-npm-package": "^1.2.1",
      },
     }
   }
   

2. Create a .npmrc file and enter your private npm registry details as shown in the following sample snippet. Check out what are npmrc files and how to set them for more information.
   
   .npmrc

   @myscope:registry=https://mycustomregistry.example.org
   

If your private npm registry needs authentication to access it, then follow the steps in the configuring NPM registry authentication section.

Registry URL is only available to your private network

If the NPM registry URL is accessible only in your private network, then complete the following steps to route requests through the BrowserStack Local tunnel connection:

1. Specify the private npm package dependency in your browserstack.json:
   
   browserstack.json

   {
     "run_settings": {
       ...
       "npm_dependencies": {
          "your-private-npm-package-accessible-only-in-your-private-network": "^1.2.1",
      },
     }
   }
   

2. Create a .npmrc file and enter your private npm registry details as shown in the following sample code snippet. Check out what are npmrc files and how to set them for more information.
   .npmrc

   @myscope:registry=https://mycustomregistry.private-staging.com
   

3. Set "local": true in the "connection_settings" section of your browserstack.json file since the URL is not publicly resolvable.
   
   browserstack.json

   ...
   {
     "connection_settings": {
       "local": true
     }
   }
   ...
   

4. If you are behind a proxy, then you need to ensure that you specify the proxy parameters in a local-config.yml file and specify the path in the browserstack.json file as shown in the following code snippet. You can see the sample config file and configure the proxy related parameters accordingly.
   browserstack.json

   ...
   {
     "connection_settings": {
       "local": true,
       "local_config_file": "/path/to/your/config.yml"
     }
   }
   ...
   

If your private npm registry needs authentication to access it, then follow the steps in the configure NPM registry authentication section.

Configure NPM registry authentication

In the earlier sections, we learnt about accessing the npm registry for both when your private npm package registry URL is publicly resolvable or privately resolvable. In this section, we will learn about the steps that you must follow if your npm registry itself needs authentication.

Accessing the npm registry involves creating an npm token, and then setting the token in the .npmrc file.

1. Create an npm token using npm token create command. Check out Creating an access token to learn about creating access tokens including CIDR-whitelisted tokens.
2. After the token is created, save it in an environment variable such as NPM_TOKEN in your system.
3. Configure the browserstack.json file as shown in the following snippet to read the specified environment variable value from your system when you trigger any Cypress test.
   browserstack.json

   ...
   "run_settings": {
     ...
     "system_env_vars": ["NPM_TOKEN", "ANY_OTHER_ENV_VARIABLE_THAT_YOU_WANT_TO_BE_AVAILABLE_AT_OS_LEVEL"]
   }
   

   After you configure the environment variable, the browserstack-cypress CLI will use this variable from your system and set the same in BrowserStack machines, and use them thereafter.

4. In the .npmrc file, specify the npm token for authentication.
   
   .npmrc

   @myscope:registry=https://mycustomregistry.example.org:_authToken=${NPM_TOKEN}
   

   Check out NPM documentation for setting authentication for CI/CD runs to learn more.

npm dependency caching

BrowserStack would cache all your npm dependencies so that every time you run a build, npm install is not required which used to take up a major part of the total time of your build execution.

Caching dependencies is a default behavior for browserstack-cypress-cli v1.11.0 and higher. Due to this behavior, all your private packages (if any) would also be cached on our servers. If you want to stop BrowserStack from caching your npm dependencies, specify the following configuration option in your browserstack.json file but your build will end up taking much longer to complete.

{
  "run_settings": {
    ...
    "cache_dependencies": "false"
  }
}