Skip to main content
Version: v5

Troubleshooting

Use this guide when you are getting started with the AudioEye Testing SDK and run into setup, installation, or first-run problems.

Before you troubleshoot​

Confirm these basics first:

  • You are using a supported Node.js version: 20, 22, or 24
  • You are installing packages from the project root, where package.json lives
  • Your project is already configured to use npm, yarn, or pnpm
  • Your entitlement token is available as the AUDIOEYE_ENTITLEMENT_TOKEN environment variable
  • Your package manager config includes the @audioeye registry settings from getting started

If one of those items is missing, go back to getting started and complete the initial setup first.

Installation and package download issues​

Package install fails with 401, 403, or authentication errors​

This usually means the package manager can reach the registry, but it is not authorized to download the package.

What to check​

  • Verify that AUDIOEYE_ENTITLEMENT_TOKEN is set in the same shell session where you run npm install or yarn install or pnpm install
  • Verify that your .npmrc or .yarnrc.yml file contains the @audioeye registry configuration from getting started
  • Verify that you copied the full token from the AudioEye Customer Portal
  • If you recently refreshed your token, update every local environment and CI/CD secret that still uses the old value

Common causes​

  • The token was copied with missing characters or trailing whitespace
  • The token exists in your shell profile, but the current terminal session has not reloaded it yet
  • The token was rotated in the portal, but your local machine or CI job still uses the previous token
  • The package manager config file was added in the wrong directory instead of the project root

Resolution​

  1. Re-copy the token from the AudioEye Customer Portal.
  2. Re-export AUDIOEYE_ENTITLEMENT_TOKEN in your current terminal session.
  3. Re-check the package manager config in the project root.
  4. Retry installation.

If the token was refreshed recently, repeat the same update in your CI/CD environment before rerunning the pipeline.

Package install fails with 404 or package not found​

This usually means the package manager is not using the AudioEye registry for the @audioeye scope.

What to check​

  • For npm or pnpm, confirm .npmrc contains:
@audioeye:registry=https://npm.cloudsmith.io/audioeye-K01/audioeye/
//npm.cloudsmith.io/audioeye-K01/audioeye/:_authToken=${AUDIOEYE_ENTITLEMENT_TOKEN}
  • For Yarn, confirm .yarnrc.yml contains:
npmScopes:
  audioeye:
    npmAlwaysAuth: true
    npmAuthToken: "${AUDIOEYE_ENTITLEMENT_TOKEN}"
    npmRegistryServer: "https://npm.cloudsmith.io/audioeye-K01/audioeye/"

Resolution​

Add the correct scoped registry configuration, save the file in your project root, and retry the install command.

Package install hangs or fails due to network issues​

If the install process is slow, times out, or fails intermittently:

What to check​

  • Your corporate VPN, proxy, or firewall is not blocking Cloudsmith
  • Your network allows outbound access to npm.cloudsmith.io
  • There is no active incident on the Cloudsmith status page

Resolution​

  • Retry on a stable network connection
  • Temporarily disable VPN or proxy settings if your company policy allows it
  • If you are in CI, rerun the job to rule out a transient network error
  • If failures persist across multiple environments, check with your network or security team

Installation works locally but fails in CI​

This usually means CI does not have access to the entitlement token or does not expose it during dependency installation.

What to check​

  • AUDIOEYE_ENTITLEMENT_TOKEN is stored as a CI secret
  • The secret is exposed in the install step, not only in test or build steps
  • The repository contains the expected .npmrc or .yarnrc.yml configuration
  • The CI job uses a supported Node.js version

Resolution​

Make sure the token is available when dependencies are installed, not after. Then rerun the job.

For setup examples, refer to getting started.

Entitlement token issues​

I do not know where to find the entitlement token​

Retrieve it from the AudioEye Customer Portal by following the steps in getting started.

I refreshed the token and installs stopped working​

Refreshing the token invalidates the previous value.

Resolution​

Update the token everywhere it is used:

  • your local shell environment
  • your shell profile such as ~/.zshrc or ~/.bashrc
  • CI/CD secret stores
  • any local developer setup notes or environment managers your team uses

After updating the token, restart the shell or open a new terminal, then retry installation.

I do not want to hardcode the token in config files​

That is the recommended approach. Use an environment variable reference instead of the literal token value.

Use the examples in getting started, where the token is referenced as AUDIOEYE_ENTITLEMENT_TOKEN.

First-run and onboarding issues​

The CLI installs, but the first scan fails​

If @audioeye/testing-sdk-cli installs successfully but aetest scan fails, the problem is usually related to the browser runtime or the scan target rather than registry authentication.

What to check​

  • Start with a simple known page first, such as the example in CLI
  • Verify that your machine can launch a Chromium-based browser
  • If you are running in Docker or CI, make sure the environment includes Chrome and the required dependencies
  • If you are scanning local HTML, verify that the file contains valid HTML and that your command points to the expected file

Resolution​

  1. Confirm installation by scanning a simple known page first.
  2. If that works, retry with your local page or HTML fixture.
  3. If you are using Docker, follow the container guidance in CLI.

The CLI works locally but fails in Docker​

The CLI needs a browser environment.

Common causes​

  • Chrome is not installed in the image
  • Required Linux dependencies are missing
  • The container is missing permissions needed by Chrome

Resolution​

Use the recommended Docker setup in CLI. If you maintain your own base image, make sure Chrome and its dependencies are installed and that the container is started with the required permissions.

I am not sure which SDK package to start with​

Use this rule of thumb:

  • Start with CLI if you want the fastest possible verification that your entitlement token and installation are working
  • Use Jest for component-level tests
  • Use Playwright or Cypress for full browser workflows
  • Use Core / custom integrations only if you need lower-level control

If you are brand new to the SDK, getting started plus the CLI guide is usually the fastest onboarding path.

Framework-specific setup issues​

Playwright setup compiles, but the accessibility fixture is not available​

This usually means your tests are still importing Playwright's default test runner instead of the AudioEye-extended runner.

Resolution​

Use one of these patterns consistently:

  • import test directly from @audioeye/testing-sdk-playwright
  • create your own shared fixture file that extends Playwright's base test, then import that local test object in every spec

If the fixture is missing in some files but not others, check for mixed imports across the test suite.

Cypress custom command is not recognized​

This usually means the SDK command registration file is not imported from your Cypress support layer.

Resolution​

Make sure:

  • @audioeye/testing-sdk-cypress is imported in cypress/support/commands.ts or cypress/support/commands.js
  • your support entry point, such as cypress/support/e2e.ts, imports ./commands
  • your project is loading the expected support file for the Cypress version you use

See Cypress for the expected setup pattern.

TypeScript errors appear in a JavaScript-only Cypress project​

If Cypress tries to process .d.ts files in a JavaScript-only setup, use the workaround documented in Cypress troubleshooting.

Jest tests run, but results seem incomplete​

The Jest SDK is designed for component-level evaluation rather than full rendered browser behavior.

What to know​

Some rules require runtime browser context, computed styles, or page-level behavior that is not available in Jest-based component tests.

Resolution​

  • Use Jest for fast component checks
  • Use Playwright or Cypress for browser-based workflows
  • Review About Our Rules to understand which rules apply in each testing scenario

Results and rule coverage questions​

Rules are not running or issues seem to be missed​

What to check​

  • Whether you are testing a component fragment or a full page
  • Whether the chosen SDK package supports the browser context required by the rule
  • Whether the page state you are testing matches the real condition where the issue appears

Resolution​

Testing production versus pre-production HTML​

The SDK is primarily designed for development and pre-production workflows, but you can still evaluate production output when needed.

Options​

  • Download the page HTML and scan it locally with the CLI
  • Scan a deployed URL directly with the CLI when that is the easiest way to reproduce the issue
  • Reproduce the same state in Playwright or Cypress if the issue appears only after user interaction or login

When to switch tools​

If you are blocked in one SDK package, the quickest resolution is sometimes to use a different package that better matches the test scenario.

  • Use CLI for quick installation verification and static page checks
  • Use Jest for fast component-level feedback
  • Use Playwright for authenticated flows, dynamic UI, and realistic browser behavior
  • Use Cypress for end-to-end application workflows in teams already standardized on Cypress

Still blocked?​

If you have completed the onboarding steps and are still blocked, gather this information before escalating:

  • Node.js version
  • package manager and version
  • whether you use npm, yarn, or pnpm
  • the SDK package you are installing
  • whether the issue occurs locally, in CI, or both
  • the exact install or runtime error message
  • whether the problem started after refreshing the entitlement token

That information makes it much faster to identify whether the issue is caused by authentication, registry configuration, browser runtime setup, or framework integration.