React Components

A component library written in React.

• Contributing
• Tool Glossary

Contributing

First follow the instructions for contributing here.

Storybook

Storybook is a tool for building UI component libraries in isolation. Once you've bootstrapped the monorepo you will be able to launch Storybook by running the following command:

This command should be ran from the package root. You can also run this command from the repo root using lerna.

$ npm run storybook

Storybook should be used to explicitly show each state your component can be in. This provides three affordances:

1. Manual Visual Testing

   A person can manually confirm that each state of your component looks right. In the future we can generate snap shots from our stories so that manual confirmation is only necessary if something changes.

   You shouldn't worry about making your component interactive. Component interactions will be tested with automated tests. Again we are only concerned with what our component looks like in different states.

2. Transparency With Design

   Our design team can visually inspect a component and use that in designs or prototypes.

3. Shared Development Environment

   An engineer can easily pickup where another engineer left off without having to create a fresh development environment for interacting with components.

   Note: This isn't your own personal playground for components. If you need a sandboxed environment for working on components you can name your private stories with the .private.stories file extension. For example, a file of the name foo.private.stories.tsx will not be checked into source control.

Writing Test

Tests are written using Jest and Enzyme. The CI pipeline is configure to fail unless a certain threshold of coverage is met. You can run the test with the following command:

This command should be ran from the package root. You can also run the tests from the repo root using lerna.

$ npm run test

Our testing strategies will evolve overtime as we evolve as engineers but I have identified two main testing criterial for interface components that I believe are a good start.

1. Testing Component Interactions

   Interaction testing involves testing users actions as they would be performed by a user on a specific platform. You could think of these as a type of integration test because they are dependent on the platform. For example, testing that clicking a button triggers some output. These types of tests SHOULD utilize Platform APIs and assert that the component responds properly to the user action.

   Note that a full platform environment is not strictly necessary. For example, jsdom is sufficient for most interactions in a browser environment.

2. Testing Component APIs

   If your component exposes a public API then these methods should be tested. For pure functions writing these tests are usually straight forward because your output is always the same given the same input (think functional programming). That is why I would recommend always making your functions pure if possible.

Tool Glossary

The following tools are used by this package:

• Boulevard Lib - A standard JavaScript library for portable modules.
• Emotion - A CSS in JS solution.
• Enzyme - A testing utility for testing React components.
• Lodash - A modern JavaScript utility library.
• ESLint - A linting utility for JavaScript.
• Jest - A JavaScript testing framework.
• JSX - A declarative JavaScript templating syntax that implements Virtual DOM.
• Material UI - Material Design components written in React.
• React - A JavaScript component syntax.
• Storybook - A development environment for UI components.
• TypeScript - JavaScript that scales.