react-native-stargazer

Stargazer 🔭

Stargazer is a tool for manual testing UI regressions in a React Native/Expo app. It records screenshots of app screens and displays these in a browser UI for side-by-side comparison. This is useful for quick reference of screen designs, product/design review sessions, or testing for UI regressions.

Development

Run the following commands to setup the project in your environment:

git clone https://github.com/tenx-tech/stargazer.git
npm run setup

This will install the project dependencies and the dependencies of each sub project (app, client, and server).

To run the project tests, run the command npm test.

Project Structure

This tool is organized into three subprojects: app, client, and server. Here's what each of these projects are responsible for:

• App: React components to provide the automation to drive the app and record screenshots of each screen.
• Client: UI browser output to visualize the recorded screenshots.
• Server: Server to handle uploading and saving screenshot data.

Workflow

Stargazer requires some setup and ongoing maintenance to be used effectively. First, you must install and setup the tool and then build a specific route configuration to provide to Stargazer. This route configuration must be maintained as your app develops. For instance, if you add a new screen to your app you will have to add it to the route configuration for it to be recorded. After this setup and overheard, you should be able to repeatedly run the tool to record your app screenshots.

Usage

To use this tool in your app first install it with npm install --save react-native-stargazer. Stargazer works by rendering the default library export Stargazer component and passing in specific props. The required props look like this:

export interface StargazerRouteConfigObject extends NavigationRouteConfig {
  name: string;
  screenName: string;
  paramsForNextScreen?: { [key: string]: any };
}

export interface StargazerProps {
  autoStart?: boolean;
  disableLogging?: boolean;
  stargazerServerUrl: string;
  routeConfig: ReadonlyArray<StargazerRouteConfigObject>;
  appRouteConfig?: NavigationRouteConfigMap;
  imageAssets?: ReadonlyArray<any>;
  fontAssets?: { [key: string]: any };
}

Primarily, a user must provide the routeConfig prop which is an array of all the screens you want to record screenshots for. Each item in the array is a StargazerRouteConfigObject which contains a name for the screen, the screenName which is used by React Navigation to identify that screen, and optional params to send to the next screen. The screens will be recorded in the order they are provided in this initial array.

Here is an example of what the routeConfig should look like:

// Stargazer Route Config:
const StargazerRouteConfig = [
  {
    name: "First Screen",
    screenName: SCREEN_NAMES.FIRST_SCREEN,
    screen: () => <FirstScreen />
  },
  {
    name: "Second Screen",
    screenName: SCREEN_NAMES.SECOND_SCREEN,
    screen: () => <SecondScreen />
  },
  {
    name: "Third Screen",
    screenName: SCREEN_NAMES.THIRD_SCREEN,
    screen: () => <ThirdScreen />
  }
];

And an example of the corresponding top level app component:

// Top Level App Component:
export default class App extends React.Component {
  render() {
    return (
      <Stargazer
        routeConfig={stargazerRoutes}
        appRouteConfig={appRoutes}
        stargazerServerUrl="http://1.2.3.4:9000/screenshot"
      />
    );
  }
}

In addition, you must supply a stargazerServerUrl which specifies the address the Stargazer server is running at. This must use your computer's IP address, e.g. http://1.2.3.4:9000/screenshot.

Now, you can add these scripts to your project's package.json:

{
  "scripts": {
    "stargazer:init": "stargazer:init",
    "stargazer:view": "stargazer:view",
    "stargazer:server": "stargazer:server"
  }
}

Now run npm run stagazer:init. This will build the output browser UI project directly into your source repository. This is simply the production build output of a Create React App which is used to render the recorded screenshots. You can check this into your source code to then deploy it and host it anywhere, or just view the screenshots locally in any development environment. Or, if you prefer to not to you can just .gitignore this output folder.

If this output UI browser ever changes in a version of react-native-stargazer you can simply re-run the init command to get a new version of the UI browser bundled output (any existing screenshot data should be preserved if it existed).

Now run npm run stargazer:server and then launch your app in another terminal tab with Expo. When you app loads on a device you should see a screen welcoming your to Stargazer. Press the blue button to start running the recording tool. Once it's finished, it will automatically upload the recorded screenshots to the stargazer-ui folder in your project directory.

Example

There is an example app in the example/ folder here. You can view that project directly to see how this tool is used with an existing Expo/React Native app.

Contributing

We welcome any changes, requests, features, improvements, or bug fixes with pull requests or welcome anyone interesting in more substantial changes to fork the library. We follow a normal git workflow process where pull requests can be reviewed and merged with approving reviews.

In general, we would like to keep the scope of this project fairly contained and avoid any major feature requests or changes.

Publishing Changes

To publish a new version of react-native-stargazer run npm run build and npm publish after incrementing the package.json project version.