Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@backstage/test-utils

backstage348.7kApache-2.01.7.7TypeScript support: included

Utilities to test Backstage plugins and apps.

backstage

readme

headline

Backstage

English | 한국어 | 中文版 | Français

License CNCF Status Discord Code style Codecov OpenSSF Best Practices OpenSSF Scorecard

What is Backstage?

Backstage is an open source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly without compromising autonomy.

Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

software-catalog

Out of the box, Backstage includes:

  • Backstage Software Catalog for managing all your software such as microservices, libraries, data pipelines, websites, and ML models
  • Backstage Software Templates for quickly spinning up new projects and standardizing your tooling with your organization’s best practices
  • Backstage TechDocs for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach
  • Plus, a growing ecosystem of open source plugins that further expand Backstage’s customizability and functionality

Backstage was created by Spotify but is now hosted by the Cloud Native Computing Foundation (CNCF) as an Incubation level project. For more information, see the announcement.

Project roadmap

For information about the detailed project roadmap including delivered milestones, see the Roadmap.

Getting Started

To start using Backstage, see the Getting Started documentation.

Documentation

The documentation of Backstage includes:

Community

To engage with our community, you can use the following resources:

Governance

See the GOVERNANCE.md document in the backstage/community repository.

License

Copyright 2020-2025 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Security

Please report sensitive security issues using Spotify's bug-bounty program rather than GitHub.

For further details, see our complete security release process.

changelog

@backstage/test-utils

1.7.7

Patch Changes

1.7.7-next.0

Patch Changes

1.7.6

Patch Changes

1.7.6-next.0

Patch Changes

1.7.5

Patch Changes

1.7.5-next.0

Patch Changes

1.7.4

Patch Changes

1.7.4-next.0

Patch Changes

1.7.3

Patch Changes

1.7.3-next.1

Patch Changes

1.7.3-next.0

Patch Changes

1.7.1

Patch Changes

1.7.1-next.0

Patch Changes

1.7.0

Minor Changes

  • 9cc7dd6: Added a mockApis export, which will replace the MockX API implementation classes and their related types. This is analogous with the backend's mockServices.

    DEPRECATED several old helpers:

    • Deprecated MockAnalyticsApi, please use mockApis.analytics instead.
    • Deprecated MockConfigApi, please use mockApis.config instead.
    • Deprecated MockPermissionApi, please use mockApis.permission instead.
    • Deprecated MockStorageApi, please use mockApis.storage instead.
    • Deprecated MockTranslationApi, please use mockApis.translation instead.

Patch Changes

1.6.1-next.2

Patch Changes

1.6.1-next.1

Patch Changes

1.6.1-next.0

Patch Changes

1.6.0

Minor Changes

  • d47be30: Added the icons option to the renderInTestApp function's TestAppOptions to be forwarded to the icons option of createApp.

Patch Changes

1.6.0-next.1

Patch Changes

1.6.0-next.0

Minor Changes

  • d47be30: Added the icons option to the renderInTestApp function's TestAppOptions to be forwarded to the icons option of createApp.

Patch Changes

1.5.10

Patch Changes

1.5.10-next.2

Patch Changes

1.5.10-next.1

Patch Changes

1.5.9-next.0

Patch Changes

1.5.8

Patch Changes

1.5.8-next.1

Patch Changes

1.5.7-next.0

Patch Changes

1.5.6

Patch Changes

1.5.6-next.2

Patch Changes

1.5.6-next.1

Patch Changes

1.5.6-next.0

Patch Changes

1.5.5

Patch Changes

1.5.5-next.0

Patch Changes

1.5.4

Patch Changes

1.5.4-next.0

Patch Changes

1.5.3

Patch Changes

1.5.2

Patch Changes

1.5.1

Patch Changes

1.5.1-next.1

Patch Changes

1.5.1-next.0

Patch Changes

1.5.0

Minor Changes

  • bb40898: Added components option to TestAppOptions, which will be forwarded as the components option to createApp.

Patch Changes

1.5.0-next.3

Patch Changes

1.5.0-next.2

Patch Changes

1.5.0-next.1

Patch Changes

1.5.0-next.0

Minor Changes

  • bb40898: Added components option to TestAppOptions, which will be forwarded as the components option to createApp.

Patch Changes

1.4.7

Patch Changes

1.4.7-next.1

Patch Changes

1.4.7-next.0

Patch Changes

1.4.6

Patch Changes

1.4.6-next.2

Patch Changes

1.4.6-next.1

Patch Changes

1.4.6-next.0

Patch Changes

1.4.5

Patch Changes

1.4.5-next.0

Patch Changes

1.4.4

Patch Changes

1.4.4-next.2

Patch Changes

1.4.4-next.1

Patch Changes

1.4.4-next.0

Patch Changes

1.4.3

Patch Changes

1.4.3-next.3

Patch Changes

1.4.3-next.2

Patch Changes

1.4.3-next.1

Patch Changes

1.4.3-next.0

Patch Changes

1.4.2

Patch Changes

1.4.2-next.0

Patch Changes

1.4.1

Patch Changes

1.4.1-next.2

Patch Changes

1.4.1-next.1

Patch Changes

1.4.1-next.0

Patch Changes

1.4.0

Minor Changes

  • 1fd38bc4141a: Test App Wrapper is now using UnifiedThemeProvider for supporting Material UI v5 next to Material UI v4 in tests.

Patch Changes

1.4.0-next.2

Patch Changes

1.4.0-next.1

Patch Changes

1.4.0-next.0

Minor Changes

  • 1fd38bc4141a: Test App Wrapper is now using UnifiedThemeProvider for supporting Material UI v5 next to Material UI v4 in tests.

Patch Changes

1.3.1

Patch Changes

1.3.1-next.2

Patch Changes

1.3.1-next.1

Patch Changes

1.3.1-next.0

Patch Changes

1.3.0

Minor Changes

  • 7908d72e033: Introduce a new global config parameter, enableExperimentalRedirectFlow. When enabled, auth will happen with an in-window redirect flow rather than through a popup window.

Patch Changes

1.3.0-next.3

Patch Changes

1.3.0-next.2

Patch Changes

1.3.0-next.1

Patch Changes

1.3.0-next.0

Minor Changes

  • 7908d72e033: Introduce a new global config parameter, enableExperimentalRedirectFlow. When enabled, auth will happen with an in-window redirect flow rather than through a popup window.

Patch Changes

1.2.6

Patch Changes

1.2.6-next.2

Patch Changes

1.2.6-next.1

Patch Changes

1.2.6-next.0

Patch Changes

1.2.5

Patch Changes

1.2.5-next.0

Patch Changes

1.2.4

Patch Changes

1.2.4-next.1

Patch Changes

1.2.4-next.0

Patch Changes

1.2.3

Patch Changes

1.2.3-next.4

Patch Changes

1.2.3-next.3

Patch Changes

1.2.3-next.2

Patch Changes

1.2.3-next.1

Patch Changes

1.2.3-next.0

Patch Changes

1.2.2

Patch Changes

1.2.2-next.0

Patch Changes

1.2.1

Patch Changes

1.2.1-next.2

Patch Changes

1.2.1-next.1

Patch Changes

1.2.1-next.0

Patch Changes

1.2.0

Minor Changes

  • 817f3196f6: Elements rendered in a test app are no longer wrapped in a Routes and Route element, as this is not compatible with React Router v6 stable.

Patch Changes

1.2.0-next.3

Patch Changes

1.2.0-next.2

Patch Changes

1.2.0-next.1

Minor Changes

  • 817f3196f6: Elements rendered in a test app are no longer wrapped in a Routes and Route element, as this is not compatible with React Router v6 stable.

Patch Changes

1.1.4-next.0

Patch Changes

1.1.3

Patch Changes

1.1.3-next.0

Patch Changes

1.1.2

Patch Changes

1.1.2-next.2

Patch Changes

1.1.2-next.1

Patch Changes

1.1.2-next.0

Patch Changes

1.1.1

Patch Changes

1.1.1-next.0

Patch Changes

1.1.0

Minor Changes

  • 1da8b248c2: Added the options parameter to renderWithEffects, which if forwarded to the render function from @testling-library/react. Initially only the wrapper option is supported.
  • 1da8b248c2: Added createTestAppWrapper, which returns a component that can be used as the wrapper option for render or renderWithEffects.

Patch Changes

1.1.0-next.2

Patch Changes

1.1.0-next.1

Minor Changes

  • 1da8b248c2: Added the options parameter to renderWithEffects, which if forwarded to the render function from @testling-library/react. Initially only the wrapper option is supported.
  • 1da8b248c2: Added createTestAppWrapper, which returns a component that can be used as the wrapper option for render or renderWithEffects.

Patch Changes

1.0.2-next.0

Patch Changes

  • 7a5ddfd595: Added missing Routes element to wrap the Route elements of the test app wrapping.
  • 7a5ddfd595: The internal elements created as part of the mountedRoutes implementation are now hidden during rendering.

1.0.1

Patch Changes

1.0.1-next.2

Patch Changes

1.0.1-next.1

Patch Changes

1.0.1-next.0

Patch Changes

1.0.0

Major Changes

  • b58c70c223: This package has been promoted to v1.0! To understand how this change affects the package, please check out our versioning policy.

Patch Changes

0.3.0

Minor Changes

  • bb2bb36651: BREAKING: Removed the deprecated get method from StorageAPI and its implementations, this method has been replaced by the snapshot method. The return value from snapshot no longer includes newValue which has been replaced by value. For getting notified when a value changes, use `observe# @backstage/test-utils.
  • af5eaa87f4: BREAKING: Removed deprecated auth0AuthApiRef, oauth2ApiRef, samlAuthApiRef and oidcAuthApiRef as these APIs are too generic to be useful. Instructions for how to migrate can be found at https://backstage.io/docs/api/deprecations#generic-auth-api-refs.

Patch Changes

0.2.6

Patch Changes

0.2.5

Patch Changes

0.2.4

Patch Changes

0.2.4-next.0

Patch Changes

0.2.3

Patch Changes

0.2.3-next.0

Patch Changes

0.2.2

Patch Changes

0.2.1

Patch Changes

  • c36b7794f7: JSON serialize and freeze values stored by the MockStorageApi.

0.2.0

Minor Changes

  • a195284c7b: Updated MockStorageApi to reflect the StorageApi changes in @backstage/core-plugin-api.
  • 771b9c07fe: Removed deprecated Keyboard class which has been superseded by @testing-library/user-event#userEvent
  • f6722d2458: Removed deprecated msw definition which was replaced by calling setupRequestMockHandlers directly

Patch Changes

0.1.24

Patch Changes

0.1.23

Patch Changes

  • 000190de69: The ApiRegistry from @backstage/core-app-api class has been deprecated and will be removed in a future release. To replace it, we have introduced two new helpers that are exported from @backstage/test-utils, namely TestApiProvider and TestApiRegistry.

    These two new helpers are more tailored for writing tests and development setups, as they allow for partial implementations of each of the APIs.

    When migrating existing code it is typically best to prefer usage of TestApiProvider when possible, so for example the following code:

    render(
  <ApiProvider
    apis={ApiRegistry.from([
      [identityApiRef, mockIdentityApi as unknown as IdentityApi]
    ])}
  >
    {...}
  </ApiProvider>
)

    Would be migrated to this:

    render(
  <TestApiProvider apis={[[identityApiRef, mockIdentityApi]]}>
    {...}
  </TestApiProvider>
)

    In cases where the ApiProvider is used in a more standalone way, for example to reuse a set of APIs across multiple tests, the TestApiRegistry can be used instead. Note that the TestApiRegistry only has a single static factory method, .from(), and it is slightly different from the existing .from() method on ApiRegistry in that it doesn't require the API pairs to be wrapped in an outer array.

    Usage that looks like this:

    const apis = ApiRegistry.with(
  identityApiRef,
  mockIdentityApi as unknown as IdentityApi,
).with(configApiRef, new ConfigReader({}));

    OR like this:

    const apis = ApiRegistry.from([
  [identityApiRef, mockIdentityApi as unknown as IdentityApi],
  [configApiRef, new ConfigReader({})],
]);

    Would be migrated to this:

    const apis = TestApiRegistry.from(
  [identityApiRef, mockIdentityApi],
  [configApiRef, new ConfigReader({})],
);

    If your app is still using the ApiRegistry to construct the apis for createApp, we recommend that you move over to use the new method of supplying API factories instead, using createApiFactory.

  • Updated dependencies

0.1.22

Patch Changes

0.1.21

Patch Changes

0.1.20

Patch Changes

  • bb12aae352: Migrates all utility methods from test-utils-core into test-utils and delete exports from the old package. This should have no impact since this package is considered internal and have no usages outside core packages.

    Notable changes are that the testing tool msw.setupDefaultHandlers() have been deprecated in favour of setupRequestMockHandlers().

  • c5bb1df55d: Bump msw to v0.35.0 to resolve CVE-2021-32796.

  • 10615525f3: Switch to use the json and observable types from @backstage/types
  • Updated dependencies

0.1.19

Patch Changes

0.1.18

Patch Changes

0.1.17

Patch Changes

0.1.16

Patch Changes

  • 9d40fcb1e: - Bumping material-ui/core version to at least 4.12.2 as they made some breaking changes in later versions which broke Pagination of the Table.
    • Switching out material-table to @material-table/core for support for the later versions of material-ui/core
    • This causes a minor API change to @backstage/core-components as the interface for Table re-exports the prop from the underlying Table components.
    • onChangeRowsPerPage has been renamed to onRowsPerPageChange
    • onChangePage has been renamed to onPageChange
    • Migration guide is here: https://material-table-core.com/docs/breaking-changes
  • Updated dependencies

0.1.15

Patch Changes

  • 45b5fc3a8: Updated the layout of catalog and API index pages to handle smaller screen sizes. This adds responsive wrappers to the entity tables, and switches filters to a drawer when width-constrained. If you have created a custom catalog or API index page, you will need to update the page structure to match the updated catalog customization documentation.
  • Updated dependencies

0.1.14

Patch Changes

0.1.13

Patch Changes

  • 7af9cef07: Fix a bug in MockStorageApi where it unhelpfully returned new empty buckets every single time
  • e7c5e4b30: Update installation instructions in README.
  • Updated dependencies [e7c5e4b30]
  • Updated dependencies [0160678b1]

0.1.12

Patch Changes

  • 61c3f927c: Updated MockErrorApi to work with new Observable type in @backstage/core.
  • Updated dependencies [61c3f927c]
  • Updated dependencies [65e6c4541]

0.1.11

Patch Changes

  • 062bbf90f: chore: bump @testing-library/user-event from 12.8.3 to 13.1.8
  • Updated dependencies [062bbf90f]
  • Updated dependencies [675a569a9]

0.1.10

Patch Changes

  • ae6250ce3: Remove unnecessary wrapping of elements rendered by wrapInTestApp and renderInTestApp, which was breaking mount discovery.
  • Updated dependencies [1279a3325]
  • Updated dependencies [4a4681b1b]
  • Updated dependencies [b051e770c]

0.1.9

Patch Changes

  • 4e0b5055a: Allow ExternalRouteRef bindings in mountedRoutes to work with the latest version of core-api.
  • Updated dependencies [a51dc0006]
  • Updated dependencies [e7f9b9435]
  • Updated dependencies [34ff49b0f]
  • Updated dependencies [d88dd219e]
  • Updated dependencies [c8b54c370]

0.1.8

Patch Changes

  • dc12852c9: Allow ExternalRouteRef instances to be passed as a route ref to mountedRoutes.
  • Updated dependencies [3a58084b6]
  • Updated dependencies [1407b34c6]
  • Updated dependencies [b6c4f485d]
  • Updated dependencies [3a58084b6]

0.1.7

Patch Changes

  • b51ee6ece: Added mountedRoutes option to wrapInTestApp, allowing routes to be associated to concrete paths to make useRouteRef usable in tested components.

0.1.6

Patch Changes

  • 1dc445e89: Update to use new plugin extension API
  • Updated dependencies [d681db2b5]
  • Updated dependencies [1dc445e89]

0.1.5

Patch Changes

0.1.4

Patch Changes

0.1.3

Patch Changes

  • Updated dependencies [1722cb53c]
  • Updated dependencies [1722cb53c]
  • Updated dependencies [902340451]

0.1.2

Patch Changes

  • Updated dependencies [28edd7d29]
  • Updated dependencies [819a70229]
  • Updated dependencies [ae5983387]
  • Updated dependencies [0d4459c08]
  • Updated dependencies [cbbd271c4]
  • Updated dependencies [3472c8be7]
  • Updated dependencies [1d0aec70f]
  • Updated dependencies [a3840bed2]
  • Updated dependencies [b79017fd3]
  • Updated dependencies [72f6cda35]
  • Updated dependencies [8c2b76e45]
  • Updated dependencies [cba4e4d97]
  • Updated dependencies [8afce088a]
  • Updated dependencies [9a3b3dbf1]
  • Updated dependencies [26e69ab1a]
  • Updated dependencies [cbab5bbf8]
  • Updated dependencies [7bbeb049f]