TestCafe Advanced Configuration
Using Node.js Runtime on Sauce Cloud
Since saucectl
v0.185.0, you can specify a Node.js runtime version on Sauce Cloud.
Only supported test runners can use configurable Node.js versions. Check the following pages for supported framework versions.
Supported Node.js Versions
Sauce Labs supports the following Node.js versions:
Node.js Version | Alias | End of Life | Removal Date |
---|---|---|---|
20.14.0 | iron, lts | October 22, 2024 | April 30, 2026 |
Environment Variable Expansion
All values in your saucectl
configuration support environment variable expansion. $var
in config.yml
will be replaced according to your shell's environment variables. References to undefined variables will be replaced with an empty string.
Predefined Environment Variables
The following environment variables are available during test execution.
Environment Variable | Description |
---|---|
SAUCE_JOB_ID | Job ID |
SAUCE_SUITE_NAME | Suite Name |
SAUCE_ARTIFACTS_DIRECTORY | Absolute path to the artifacts directory. Files placed in this folder are persisted with the Job. |
Tailoring Your Test File Bundle
The saucectl
command line bundles your root directory (rootDir
parameter of config.yml
) and transmits it to the Sauce Labs cloud, then unpacks the bundle and runs the tests. This functionality is partly what allows Sauce Control to operate in a framework-agnostic capacity. However, you can and should manage the inclusion and exclusion of files that get bundled to optimize performance and ensure security.
Excluding Files from the Bundle
The .sauceignore
file allows you to designate certain files to be excluded from bundling.
Add any files that are not direct test dependencies to .sauceignore
to reduce the size of your bundle, improve test speed, and protect sensitive information.
Examples of what can be included in .sauceignore
:
# .sauceignore
# Ignore node_modules
node_modules/
# Ignore all log files
*.log
# Ignore executables/binaries
*.exe
*.bin
**/*/bin
# Ignore media files
*.png
*.jpeg
*.jpg
*.mp4
# Ignore documentation
*.rst
*.md
# Ignore sensitive data
credentials.yml
Sometimes it's easier to do the inverse: Including files for the bundle.
# Ignore all files by default.
/*
# Re-include files we selectively want as part of the payload by prefixing the lines with '!'.
!/node_modules
!/cypress
!cypress.config.js
# Since the whole '/cypress' folder is now included, this would also include any
# subdirectories that potentially contain auto-generated test artifacts from
# the local dev environment.
# It'd be wasteful to include them in the payload, so let's ignore those subfolders.
/cypress/videos/
/cypress/results/
/cypress/screenshots/
Including Node Dependencies
The default .sauceignore
file lists node_modules/
so locally installed node dependencies are excluded from the bundle. If your tests require node dependencies to run, you can either:
Remove "node_modules" from .sauceignore
Delete or comment out node_modules/
in your .sauceignore
file to bundle your node dependencies. For example,
# Do NOT exclude node_modules from bundle
# node_modules/
Node dependencies can increase your bundle by potentially hundreds of megabytes, so consider including only the required dependencies rather than the entire node_modules
directory. The following sections provide some methods for limiting the scope of dependencies you must include.
Install "devDependencies" Only
Consider only installing NPM devDependencies
if your tests do not require all prod dependencies
.
# Only install dev dependencies
npm install --only=dev
saucectl run
Uninstall Nonessential Dependencies
If your standard install includes dependencies that aren't needed to run your tests, uninstall them prior to bundling.
# Install node dependencies
npm ci # or "npm install"
# Remove unneeded dependencies
npm uninstall appium
npm uninstall express
saucectl run
Install Essential Dependencies Individually
If you know that your tests require only specific dependencies, install them individually instead of running npm install
or npm ci
.
# Install individual dependencies
npm install playwright-xpath
saucectl run
Set NPM Packages in config.yml
You can avoid installing or uninstalling dependencies prior to each bundling operation by defining a default set of NPM packages to install in your sauce configuration file using the npm
parameter, as shown in the following example:
npm:
registries:
- url: https://registry.npmjs.org
packages:
"lodash": "4.17.20"
Alternatively, you can let saucectl
selectively include already installed dependencies from the node_modules
folder.
npm:
dependencies:
- lodash
If a package.json
file is specified, saucectl
will automatically include all
locally installed dependencies
and devDependencies
listed in the
package.json
file. While this may seem convenient at first, it can lead to
long startup times if the package.json
file includes dependencies that are
not strictly required for the test run.
npm:
dependencies:
- "package.json"
This feature is highly experimental.
Attaching Test Assets
By default, any test assets created by your tests at runtime (such as logs, screenshots or reports) you wish to retain along with your test results must be placed in the __assets__
directory of your project root folder. On Sauce Labs VMs, this path is relative to the current working directory.
Attaching entire directories
In situations where you want to preserve the file structure of your assets (e.g. a multi-page HTML report),
you can use the retain
feature to define a directory to archive and store as a test asset.
Handling nested assets
Nested assets are stored flat in Sauce Labs. A test asset like __assets__/mylogs/log.txt
would therefore be stored and available for download as log.txt
.
Please keep that in mind when creating custom assets, as examples like __assets__/mylogs/log.txt
and __assets__/myotherlogs/log.txt
would eventually collide when persisted.
For Cypress and Playwright, there are cases where you may want to override this default behavior; e.g. your test framework generates
an HTML report and you want to preserve the entire report directory and don't want the individual files to
be flattened and automatically attached as described above. In that case, you can set an environment variable
in your saucectl config to opt out of the default behaviour. When set, the configured output directory
for the test run will be honoured; e.g. it won't be overridden to __assets__/
.
artifacts:
retain:
report-directory: archived-report.zip
env:
SAUCE_SYNC_WEB_ASSETS: "true"
When configured this way, the directory named report-directory
will be archived as archived-report.zip
.
To maintain backwards compatibility with our UI, some asset types (e.g. images, logs, etc.) in report-directory
will still be automatically copied over to __assets__/
and attached to the test results.
Setting up a Proxy
If you need to go through a proxy server, you can set it through the following variables:
HTTP_PROXY
: Proxy to use to access HTTP websitesHTTPS_PROXY
: Proxy to use to access HTTPS websites
Setting a Custom Firefox Profile
If you ever have the need to mock video streams, such as a webcam, the browser needs to be configured accordingly. Firefox does not provide a browser arg to enable all flags necessary—they have to be set via the profile settings.
This example illustrates how you can configure saucectl to make use of an existing preconfigured browser profile.