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

Package detail

@backstage/backend-test-utils

backstage193.9kApache-2.01.4.0TypeScript support: included

Test helpers library for Backstage backends

backstage, test

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/backend-test-utils

1.4.0

Minor Changes

  • cf4eb13: Added actor property to BackstageUserPrincipal containing the subject of the last service (if any) who performed authentication on behalf of the user.

Patch Changes

1.3.2-next.2

Patch Changes

1.3.2-next.1

Patch Changes

1.3.2-next.0

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

  • dd05a97: Added mocks for the new PermissionsRegistryService.
  • a4aa244: This change introduces mocks for the auditor service.

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

  • dd05a97: Added mocks for the new PermissionsRegistryService.
  • a4aa244: This change introduces mocks for the auditor service.

Patch Changes

1.2.1

Patch Changes

1.2.1-next.1

Patch Changes

1.2.1-next.0

Patch Changes

1.2.0

Minor Changes

  • de6f280: BREAKING Upgraded @keyv/redis and keyv packages to resolve a bug related to incorrect resolution of cache keys.

    This is a breaking change for clients using the redis store for cache with useRedisSets option set to false since cache keys will be calculated differently (without the sets:namespace: prefix). For clients with default configuration (or useRedisSets set to false) the cache keys will stay the same, but since @keyv/redis library no longer supports redis sets they won't be utilised anymore.

    If you were using useRedisSets option in configuration make sure to remove it from app-config.yaml:

    backend:
  cache:
    store: redis
    connection: redis://user:pass@cache.example.com:6379
-   useRedisSets: false

Patch Changes

1.2.0-next.2

Patch Changes

1.2.0-next.1

Patch Changes

1.2.0-next.0

Minor Changes

  • de6f280: BREAKING Upgraded @keyv/redis and keyv packages to resolve a bug related to incorrect resolution of cache keys.

    This is a breaking change for clients using the redis store for cache with useRedisSets option set to false since cache keys will be calculated differently (without the sets:namespace: prefix). For clients with default configuration (or useRedisSets set to false) the cache keys will stay the same, but since @keyv/redis library no longer supports redis sets they won't be utilised anymore.

    If you were using useRedisSets option in configuration make sure to remove it from app-config.yaml:

    backend:
  cache:
    store: redis
    connection: redis://user:pass@cache.example.com:6379
-   useRedisSets: false

Patch Changes

1.1.0

Minor Changes

  • 5064827: Made it possible to construct mockServices.database with a given knex instance

Patch Changes

1.1.0-next.3

Patch Changes

1.1.0-next.2

Minor Changes

  • 5064827: Made it possible to construct mockServices.database with a given knex instance

Patch Changes

1.0.3-next.1

Patch Changes

1.0.3-next.0

Patch Changes

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

  • ec1b4be: Release 1.0 of the new backend system! :tada:

    The backend system is finally getting promoted to 1.0.0. This means that the API is now stable and breaking changes should not occur until version 2.0.0, see our package versioning policy for more information what this means.

    This release also marks the end of the old backend system based on createRouter exports. Going forward backend plugins packages will start to deprecate and later this year remove exports supporting the old backend system. If you would like to help out with this transition, see https://github.com/backstage/backstage/issues/26353 or consult the migration guide.

Minor Changes

  • 19ff127: BREAKING: Removed service mocks for the identity and token manager services, which have been removed from @backstage/backend-plugin-api.

  • d425fc4: BREAKING: The return values from createBackendPlugin, createBackendModule, and createServiceFactory are now simply BackendFeature and ServiceFactory, instead of the previously deprecated form of a function that returns them. For this reason, createServiceFactory also no longer accepts the callback form where you provide direct options to the service. This also affects all coreServices.* service refs.

    This may in particular affect tests; if you were effectively doing createBackendModule({...})() (note the parentheses), you can now remove those extra parentheses at the end. You may encounter cases of this in your packages/backend/src/index.ts too, where you add plugins, modules, and services. If you were using createServiceFactory with a function as its argument for the purpose of passing in options, this pattern has been deprecated for a while and is no longer supported. You may want to explore the new multiton patterns to achieve your goals, or moving settings to app-config.

    As part of this change, the IdentityFactoryOptions type was removed, and can no longer be used to tweak that service. The identity service was also deprecated some time ago, and you will want to migrate to the new auth system if you still rely on it.

Patch Changes

1.0.0-next.2

Major Changes

  • ec1b4be: Release 1.0 of the new backend system! :tada:

    The backend system is finally getting promoted to 1.0.0. This means that the API is now stable and breaking changes should not occur until version 2.0.0, see our package versioning policy for more information what this means.

    This release also marks the end of the old backend system based on createRouter exports. Going forward backend plugins packages will start to deprecate and later this year remove exports supporting the old backend system. If you would like to help out with this transition, see https://github.com/backstage/backstage/issues/26353 or consult the migration guide.

Patch Changes

0.6.0-next.1

Patch Changes

0.6.0-next.0

Minor Changes

  • 19ff127: BREAKING: Removed service mocks for the identity and token manager services, which have been removed from @backstage/backend-plugin-api.

  • d425fc4: BREAKING: The return values from createBackendPlugin, createBackendModule, and createServiceFactory are now simply BackendFeature and ServiceFactory, instead of the previously deprecated form of a function that returns them. For this reason, createServiceFactory also no longer accepts the callback form where you provide direct options to the service. This also affects all coreServices.* service refs.

    This may in particular affect tests; if you were effectively doing createBackendModule({...})() (note the parentheses), you can now remove those extra parentheses at the end. You may encounter cases of this in your packages/backend/src/index.ts too, where you add plugins, modules, and services. If you were using createServiceFactory with a function as its argument for the purpose of passing in options, this pattern has been deprecated for a while and is no longer supported. You may want to explore the new multiton patterns to achieve your goals, or moving settings to app-config.

    As part of this change, the IdentityFactoryOptions type was removed, and can no longer be used to tweak that service. The identity service was also deprecated some time ago, and you will want to migrate to the new auth system if you still rely on it.

Patch Changes

0.5.0

Minor Changes

  • 861f162: BREAKING: Removed these deprecated helpers:

    • setupRequestMockHandlers is removed; use registerMswTestHooks instead.
    • MockDirectoryOptions is removed; use CreateMockDirectoryOptions instead.

    Stopped exporting the deprecated and internal isDockerDisabledForTests helper.

    Removed get method from ServiceFactoryTester which is replaced by getSubject

Patch Changes

0.4.5-next.3

Patch Changes

0.4.5-next.2

Patch Changes

0.4.5-next.1

Patch Changes

0.4.5-next.0

Patch Changes

0.4.4

Patch Changes

  • 2f99178: The ServiceFactoryTest.get method was deprecated and the ServiceFactoryTest.getSubject should be used instead. The getSubject method has the same behavior, but has a better method name to indicate that the service instance returned is the subject currently being tested.
  • edf5cc3: The function isDockerDisabledForTests is deprecated and will no longer be exported in the near future as it should only be used internally.
  • b05e1e1: Service factories exported by this package have been updated to use the new service factory format that doesn't use a callback.
  • fce7887: Added mock for the Root Health Service in mockServices.
  • 906c817: Updated startTestBackend and ServiceFactoryTester to only accept plain service factory or backend feature objects, no longer supporting the callback form. This lines up with the changes to @backstage/backend-plugin-api and should not require any code changes.
  • 95a3a0b: Rename frontend and backend setupRequestMockHandlers methods to registerMswTestHooks.
  • b9ed1bb: bumped better-sqlite3 from ^9.0.0 to ^11.0.0
  • 98ccf00: Internal refactor of mockServices.httpAuth.factory to allow it to still be constructed with options, but without declaring options via createServiceFactory.
  • Updated dependencies

0.4.4-next.1

Patch Changes

0.4.3-next.0

Patch Changes

0.4.0

Minor Changes

  • 805cbe7: Added TestCaches that functions just like TestDatabases

Patch Changes

0.4.0-next.3

Patch Changes

0.4.0-next.2

Patch Changes

0.4.0-next.1

Minor Changes

  • 805cbe7: Added TestCaches that functions just like TestDatabases

Patch Changes

0.3.9-next.0

Patch Changes

0.3.8

Patch Changes

0.3.8-next.2

Patch Changes

0.3.8-next.1

Patch Changes

0.3.8-next.0

Patch Changes

0.3.7

Patch Changes

0.3.7-next.1

Patch Changes

0.3.7-next.0

Patch Changes

0.3.6

Patch Changes

0.3.5

Patch Changes

0.3.4

Patch Changes

0.3.4-next.2

Patch Changes

0.3.4-next.1

Patch Changes

0.3.3-next.0

Patch Changes

0.3.0

Minor Changes

  • e85aa98: drop databases after unit tests if the database instance is not running in docker

Patch Changes

0.3.0-next.3

Patch Changes

0.3.0-next.2

Patch Changes

0.3.0-next.1

Patch Changes

0.3.0-next.0

Minor Changes

  • e85aa98: drop databases after unit tests if the database instance is not running in docker

Patch Changes

0.2.10

Patch Changes

0.2.10-next.2

Patch Changes

0.2.10-next.1

Patch Changes

0.2.10-next.0

Patch Changes

0.2.9

Patch Changes

0.2.9-next.3

Patch Changes

0.2.9-next.2

Patch Changes

0.2.9-next.1

Patch Changes

0.2.9-next.0

Patch Changes

0.2.8

Patch Changes

0.2.8-next.2

Patch Changes

0.2.8-next.1

Patch Changes

0.2.8-next.0

Patch Changes

0.2.7

Patch Changes

0.2.7-next.2

Patch Changes

0.2.6-next.1

Patch Changes

0.2.6-next.0

Patch Changes

0.2.3

Patch Changes

0.2.3-next.3

Patch Changes

0.2.3-next.2

Patch Changes

0.2.3-next.1

Patch Changes

0.2.2-next.0

Patch Changes

0.2.0

Minor Changes

  • b9c57a4f857e: BREAKING: Renamed mockServices.config to mockServices.rootConfig.

  • a6d7983f349c: BREAKING: Removed the services option from createBackend. Service factories are now BackendFeatures and should be installed with backend.add(...) instead. The following should be migrated:

    const backend = createBackend({ services: [myCustomServiceFactory] });

    To instead pass the service factory via backend.add(...):

    const backend = createBackend();
backend.add(customRootLoggerServiceFactory);

Patch Changes

0.2.0-next.2

Patch Changes

0.2.0-next.1

Minor Changes

  • b9c57a4f857e: BREAKING: Renamed mockServices.config to mockServices.rootConfig.

Patch Changes

0.1.40-next.0

Patch Changes

0.1.39

Patch Changes

0.1.39-next.0

Patch Changes

0.1.38

Patch Changes

0.1.38-next.2

Patch Changes

0.1.38-next.1

Patch Changes

0.1.38-next.0

Patch Changes

0.1.37

Patch Changes

0.1.37-next.1

Patch Changes

0.1.37-next.0

Patch Changes

0.1.36

Patch Changes

0.1.36-next.2

Patch Changes

0.1.36-next.1

Patch Changes

0.1.36-next.0

Patch Changes

0.1.35

Patch Changes

0.1.35-next.2

Patch Changes

0.1.35-next.1

Patch Changes

0.1.35-next.0

Patch Changes

0.1.34

Patch Changes

  • baf6e4c96a: Removed unnecessary @backstage/cli dependency.
  • c51efce2a0: Update docs to always use yarn add --cwd for app & backend
  • 1835311713: Added explicit return type signature for mockServices.config().
  • e716946103: Updated usage of the lifecycle service.
  • 7e7557a2be: Updated the mockServices.rootLogger options to accept a single level option instead.
  • 610d65e143: Updates to match new BackendFeature type.
  • e412d33025: Use the new *ServiceFactory exports from @backstage/backend-app-api
  • b86efa2d04: Updated usage of ServiceFactory.
  • 17b573e4be: The new backend system testing utilities have now been marked as stable API.
  • f1adb2e36b: Removed the ref from all mockServices.
  • d0901c9ba4: All mock service factories and mock service implementations are now available via the new experimental mockServices export.
  • 71a5ec0f06: Updated usages of LogMeta.
  • Updated dependencies

0.1.34-next.2

Patch Changes

0.1.34-next.1

Patch Changes

0.1.34-next.0

Patch Changes

0.1.32

Patch Changes

0.1.32-next.2

Patch Changes

0.1.32-next.1

Patch Changes

0.1.32-next.0

Patch Changes

0.1.31

Patch Changes

0.1.31-next.4

Patch Changes

0.1.31-next.3

Patch Changes

0.1.31-next.2

Patch Changes

0.1.31-next.1

Patch Changes

0.1.31-next.0

Patch Changes

0.1.30

Patch Changes

0.1.30-next.1

Patch Changes

0.1.30-next.0

Patch Changes

0.1.29

Patch Changes

0.1.29-next.2

Patch Changes

0.1.29-next.1

Patch Changes

0.1.29-next.0

Patch Changes

0.1.28

Patch Changes

0.1.28-next.3

Patch Changes

0.1.28-next.2

Patch Changes

0.1.28-next.1

Patch Changes

0.1.28-next.0

Patch Changes

0.1.27

Patch Changes

0.1.27-next.0

Patch Changes

0.1.26

Patch Changes

0.1.26-next.3

Patch Changes

0.1.26-next.2

Patch Changes

0.1.26-next.1

Patch Changes

0.1.26-next.0

Patch Changes

0.1.25

Patch Changes

0.1.25-next.2

Patch Changes

0.1.25-next.1

Patch Changes

0.1.25-next.0

Patch Changes

0.1.24

Patch Changes

0.1.24-next.1

Patch Changes

0.1.24-next.0

Patch Changes

0.1.23

Patch Changes

0.1.23-next.1

Patch Changes

0.1.23-next.0

Patch Changes

0.1.22

Patch Changes

0.1.21

Patch Changes

  • ab7cd7d70e: Do some groundwork for supporting the better-sqlite3 driver, to maybe eventually replace @vscode/sqlite3 (#9912)
  • 3c2bc73901: Add setupRequestMockHandlers which sets up a good msw server foundation, copied from @backstage/test-utils which is a frontend-only package and should not be used from backends.
  • Updated dependencies

0.1.21-next.0

Patch Changes

  • ab7cd7d70e: Do some groundwork for supporting the better-sqlite3 driver, to maybe eventually replace @vscode/sqlite3 (#9912)
  • 3c2bc73901: Add setupRequestMockHandlers which sets up a good msw server foundation, copied from @backstage/test-utils which is a frontend-only package and should not be used from backends.
  • Updated dependencies

0.1.20

Patch Changes

0.1.19

Patch Changes

0.1.18

Patch Changes

0.1.17

Patch Changes

0.1.17-next.0

Patch Changes

0.1.16

Patch Changes

0.1.16-next.1

Patch Changes

0.1.16-next.0

Patch Changes

0.1.15

Patch Changes

0.1.14

Patch Changes

0.1.14-next.0

Patch Changes

0.1.13

Patch Changes

0.1.12

Patch Changes

0.1.11

Patch Changes

0.1.10

Patch Changes

0.1.9

Patch Changes

0.1.8

Patch Changes

0.1.7

Patch Changes

0.1.6

Patch Changes

0.1.5

Patch Changes

0.1.4

Patch Changes

0.1.3

Patch Changes

  • 772dbdb51: Deprecates SingleConnectionDatabaseManager and provides an API compatible database connection manager, DatabaseManager, which allows developers to configure database connections on a per plugin basis.

    The backend.database config path allows you to set prefix to use an alternate prefix for automatically generated database names, the default is backstage_plugin_. Use backend.database.plugin.<pluginId> to set plugin specific database connection configuration, e.g.

    backend:
  database:
    client: 'pg',
    prefix: 'custom_prefix_'
    connection:
      host: 'localhost'
      user: 'foo'
      password: 'bar'
    plugin:
      catalog:
        connection:
          database: 'database_name_overriden'
      scaffolder:
        client: 'sqlite3'
        connection: ':memory:'

    Migrate existing backstage installations by swapping out the database manager in the packages/backend/src/index.ts file as shown below:

    import {
-  SingleConnectionDatabaseManager,
+  DatabaseManager,
} from '@backstage/backend-common';

// ...

function makeCreateEnv(config: Config) {
  // ...
-  const databaseManager = SingleConnectionDatabaseManager.fromConfig(config);
+  const databaseManager = DatabaseManager.fromConfig(config);
  // ...
}

  • Updated dependencies

0.1.2

Patch Changes

  • 0711954a9: Skip running docker tests unless in CI
  • Updated dependencies [9cd3c533c]
  • Updated dependencies [92963779b]
  • Updated dependencies [7f7443308]
  • Updated dependencies [21e8ebef5]
  • Updated dependencies [eda9dbd5f]