Skip to content

Latest commit

 

History

History

devtools-view

README.md

@fluid-internal/devtools-view

This library contains a simple view for visualizing data generated by Fluid Devtools.

This library also powers our Chrome Extension: @fluid-internal/devtools-browser-extension.

IMPORTANT: This package is intended strictly as an implementation detail of the Fluid Framework and is not intended for public consumption. We make no stability guarantees regarding its APIs.

Usage

This library has 2 primary entry-points:

  1. A React component: DevtoolsPanel.
  2. An environment-agnostic rendering hook: TODO.

Working in the package

Prerequisites

Git LFS

The Visual Regression Tests utilized by this package generate image assets that are tracked using Git LFS. Before running those tests in this package, ensure you have installed LFS (run git lfs install if you're on a UNIX-based environment; in Windows, Git for Windows installs it by default).

Build

To build the package locally, first ensure you have run pnpm install from the root of the mono-repo. Next, to build the code, run npm run build from the root of the mono-repo, or use fluid-build via fluid-build -t build.

  • Note: Once you have run a build from the root, assuming no other changes outside of this package, you may run npm run build directly within this directory for a faster build. If you make changes to any of this package's local dependencies, you will need to run a build again from the root before building again from directly within this package.

Testing

This package uses 2 flavors of testing:

  1. Component-level unit tests
  2. Visual regression "tests"

To run all of the tests, run npm run test from a terminal within this directory. Note: you will need to have built the code before running the unit tests.

Unit Tests

This package uses jest and testing-library/react to power its unit tests. The corresponding test modules can be found under src/test.

To run only the unit tests, first ensure you have followed the build steps above. Next, run npm run test:jest from a terminal within this directory.

Visual Regression Tests

In addition to our unit tests, we also utilize image-based visual regression tests to ensure our theming / styling are as expected. These run using mocha. This is particularly important for ensuring we meet our visual accessibility requirements.

The test modules for these tests are written using Storybook "stories" and live under src/screenshot-tests. The corresponding screenshot assets live under ./__screenshots__.

To run only the visual regression tests, run npm run test:screenshots from a terminal within this directory.

Adding a new test story

To add a new test story, do the following:

  1. Add a new file under the src/screenshot-tests/stories using the following naming convention: <name-of-the-component-being-tested>.stories.tsx.

    • The idea is to have a 1-1 mapping of stories modules to components. Each stories module may contain any number of stories, where each story maps to a single test.

  2. Add the top-level story module boilerplate. I.e.

    // PreviewJS doesn't handle roll-up modules correctly. Must import directly from component module.
import { COMPONENT_NAME } from "../../components/COMPONENT_NAME";
import { testContextDecorator } from "../ScreenshotTestUtilities";

export default {
	title: "COMPONENT_NAME",
	component: COMPONENT_NAME,
	decorators: [testContextDecorator],
};

  3. Then, add the individual test stories required to test the component. E.g.

    /**
 * <Description of the story>
 */
export const STORY_NAME = {
	args: {
		// Component props describing the story
		foo: 42,
		bar: "baz",
	},
};

  4. Run the tests via npm run test:screenshots (npm run test will also run the screenshot tests, alongside the others).

  5. Look at the generated screenshots, verify that the output looks correct, and check them in!

What to do when a test fails?

If you have made code changes, and 1 or more of the screenshot tests have started failing, compare the newly generated screenshot with the existing version checked into the repo. If the changes are expected / look correct, go ahead and check in the new versions(s). If not, make the necessary code changes and re-run.

Note: Since we're using Git LFS to store the screenshot assets, performing the diff comparison locally can be a bit tricky. Fortunately, Github's LFS diffing works pretty well. If you are unsure of the screenshot changes you're seeing, you can always view the commit in Github to see a side-by-side comparison.

Contribution Guidelines

There are many ways to contribute to Fluid.

Detailed instructions for working in the repo can be found in the Wiki.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.

Help

Not finding what you're looking for in this README? Check out our GitHub Wiki or fluidframework.com.

Still not finding what you're looking for? Please file an issue.

Thank you!

Trademark

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.

Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.

Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.