@render-with/backstage NPM

Render decorators 🪆 for Backstage

GitHub Workflow Status npm (scoped) NPM

Use one of these decorators if your component under test requires a Backstage an app context or an ApiProvider:

withApp()
withApis(..)

Example:

import { render, screen, withApis } from './test-utils'

// ...

it('fetches data', () => {
  render(<Plugin />, withApis(apis))
  expect(fetchMock).toHaveBeenCalledWith('http://url')
})

Note: Refer to the core library to learn more about how decorators can simplify writing tests for React components with React Testing Library.

Installation

This library is distributed via npm, which is bundled with node and should be installed as one of your project's devDependencies.

First, install the core library with a render function that supports decorators:

npm install --save-dev @render-with/decorators

Next, install the Backstage decorators provided by this library:

npm install --save-dev @render-with/backstage

for installation via yarn:

yarn add --dev @render-with/decorators
yarn add --dev @render-with/backstage

This library has the following peerDependencies:

npm peer dependency version

and supports the following node versions:

node-current (scoped)

Setup

In your test-utils file, re-export the render function that supports decorators and the Backstage decorators:

// test-utils.js
// ...
export * from '@testing-library/react'  // makes all React Testing Library's exports available
export * from '@render-with/decorators' // overrides React Testing Library's render function
export * from '@render-with/backstage'  // makes decorators like withApis(..) available

And finally, use the Backstage decorators in your tests:

import { render, screen, withApis } from './test-utils'

// ...

it('fetches data', () => {
  render(<Plugin />, withApis(apis))
  expect(fetchMock).toHaveBeenCalledWith('http://url')
})

Test Scenarios

Need to provide certain API implementations?

If your component under test requires certain API implementations to function, use the withApis(..) decorator:

import { render, screen, withApis } from './test-utils'

const fetchMock = jest.fn()

const apis = TestApiRegistry.from(
  [ fetchApiRef, { fetch: fetchMock } ],
)

it('fetches data', () => {
  render(<Plugin />, withApis(apis))
  expect(fetchMock).toHaveBeenCalledWith('http://url')
})

Need to provide an app context?

If your component under test requires a Backstage app context, use the withApp() decorator:

import { render, screen, withApp } from './test-utils'

it('fetches data', () => {
  render(<Plugin />, withApp())
  expect(screen.getByRole('button', { name: /submit/i })).toBeDisabled()
})

API

Note: This API reference uses simplified types. You can find the full type specification here.

function withApp(): Decorator

Wraps component under test in a Backstage AppContext.Provider.

function withApis(apis: ApiHolder): Decorator

Wraps component under test in a Backstage ApiProvider using the given list of APIs.

Issues

Looking to contribute? PRs are welcome. Checkout this project's Issues on GitHub for existing issues.

🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

See Bugs

💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

See Feature Requests

📚 More Libraries

Please file an issue on the core project to suggest additional libraries that would benefit from decorators. Vote on library support adding a 👍. This helps maintainers prioritize what to work on.

See Library Requests