Skip to content

Commit

Permalink
fixed duplication of local test execution instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
Syneva Runyan committed Nov 3, 2017
1 parent b0b2344 commit 1e9538c
Showing 1 changed file with 150 additions and 71 deletions.
221 changes: 150 additions & 71 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ No software is bug free. So, if you got an issue, follow these steps:

To test your project against the current latest version of storybook, you can clone the repository and link it with `yarn`. Try following these steps:

1. Download the latest version of this project, and build it:
#### 1. Download the latest version of this project, and build it:

```sh
git clone https://github.com/storybooks/storybook.git
Expand All @@ -31,71 +31,43 @@ yarn install
yarn bootstrap --core
```

2. Link `storybook` and any other required dependencies:
The bootstrap command will ask which sections of the codebase you want to bootstrap. Unless you're going to work with ReactNative or the Documentation, you can keep the default.

```sh
cd app/react
yarn link

cd <your-project>
yarn link @storybook/react
You can also pick directly from CLI:

# repeat with whichever other parts of the monorepo you are using.
```
yarn bootstrap --core

### Reproductions
#### 2a. Run unit tests

The best way to help figure out an issue you are having is to produce a minimal reproduction against the `master` branch.
You can use one of the example projects in `examples/` to develop on.

A good way to do that is using the example `cra-kitchen-sink` app embedded in this repository:
This command will list all the suites and options for running tests.

```sh
# Download and build this repository:
git clone https://github.com/storybooks/storybook.git
cd storybook
yarn install
yarn bootstrap --core

cd examples/cra-kitchen-sink

# make changes to try and reproduce the problem, such as adding components + stories
yarn storybook

# see if you can see the problem, if so, commit it:
git checkout "branch-describing-issue"
git add -A
git commit -m "reproduction for issue #123"

# fork the storybook repo to your account, then add the resulting remote
git remote add <your-username> https://github.com/<your-username>/storybook.git
git push -u <your-username> master
yarn test
```

If you follow that process, you can then link to the github repository in the issue. See <https://github.com/storybooks/storybook/issues/708#issuecomment-290589886> for an example.

**NOTE**: If your issue involves a webpack config, create-react-app will prevent you from modifying the _app's_ webpack config, however you can still modify storybook's to mirror your app's version of storybook. Alternatively, use `yarn eject` in the CRA app to get a modifiable webpack config.
The options for running tests can be selected from the cli or be passed to `yarn test` with specific parameters. Available modes include `--watch`, `--coverage`, and `--runInBand`, which will respectively run tests in watch mode, output code coverage, and run selected test suites serially in the current process.

### Executing Tests Locally
_Note that in order to run the tests fro ReactNative, you must have bootstrapped with ReactNative enabled. You can do this with the `yarn bootstrap --reactnative` command_

Tests can be executed locally with the `yarn test` command, which gives you CLI options to execute various test suites in different modes. Some of the test suites have special set-up needs, which are listed below.
You can also pick suites from CLI. Suites availabe are listed below.

The execution modes available can be selected from the cli or passed to `yarn test` with specific parameters. Available modes include `--watch`, `--coverage`, and `--runInBand`, which will respectively run tests in watch mode, output code coverage, and run selected test suites serially in the current process.

#### Core & React & Vue Tests
##### Core & React & Vue Tests

`yarn test --core`

This option executes test from `<rootdir>/app/react`, `<rootdir>/app/vue`, and `<rootdir>/lib`
Before the tests are ran, the project must be bootstrapped with core. You can accomplish this with `yarn bootstrap --core`

#### React-Native example Tests
##### React-Native example Tests

`yarn test --reactnative`

This option executes tests from `<rootdir>/app/react-native`
Before these tests are ran, the project must be bootstrapped with the React Native example enabled. You can accomplish this by running `yarn bootstrap --reactnative`

#### Integration Tests (Screenshots of running apps)
##### Integration Tests (Screenshots of running apps)

`yarn test --integration`

Expand All @@ -104,6 +76,68 @@ In order for the snapshot-integration tests to be executed properly, examples be

Puppeteer is used to launch and grab screenshots of example pages, while jest is used to assert matching images.


In order to run ALL unit tests, you must have bootstrapped the react-native

#### 2b. Run e2e tests for CLI

If you made any changes to `lib/cli` package, the easiest way to verify that it doesn't break anything is to run e2e tests:

yarn test --cli

This will run a bash script located at `lib/cli/test/run_tests.sh`. It will copy the contents of `fixtures` into a temporary `run` directory, run `getstorybook` in each of the subdirectories, and check that storybook starts successfully using `yarn storybook --smoke-test`.

After that, the `run` directory content will be compared with `snapshots`. You can update the snapshots by passing an `--update` flag:

yarn test --cli --update

In that case, please check the git diff before commiting to make sure it only contains the intended changes.

#### 2c. Link `storybook` and any other required dependencies:

If you want to test your own existing project using the github version of storybook, you need to `link` the packages you use in your project.

````sh
cd app/react
yarn link

cd <your-project>
yarn link @storybook/react

# repeat with whichever other parts of the monorepo you are using.
```

### Reproductions

The best way to help figure out an issue you are having is to produce a minimal reproduction against the `master` branch.

A good way to do that is using the example `cra-kitchen-sink` app embedded in this repository:

```sh
# Download and build this repository:
git clone https://github.com/storybooks/storybook.git
cd storybook
yarn install
yarn bootstrap --core
# make changes to try and reproduce the problem, such as adding components + stories
cd examples/cra-kitchen-sink
yarn storybook
# see if you can see the problem, if so, commit it:
git checkout "branch-describing-issue"
git add -A
git commit -m "reproduction for issue #123"
# fork the storybook repo to your account, then add the resulting remote
git remote add <your-username> https://github.com/<your-username>/storybook.git
git push -u <your-username> master
````
If you follow that process, you can then link to the github repository in the issue. See <https://github.com/storybooks/storybook/issues/708#issuecomment-290589886> for an example.
**NOTE**: If your issue involves a webpack config, create-react-app will prevent you from modifying the _app's_ webpack config, however you can still modify storybook's to mirror your app's version of storybook. Alternatively, use `yarn eject` in the CRA app to get a modifiable webpack config.
### Updating Tests
Before any contributes are submitted in a PR, make sure to add or update meaningful tests. A PR that has failing tests will be regarded as a “Work in Progress” and will not be merged until all tests pass.
Expand All @@ -127,6 +161,7 @@ await page.goto('http://localhost:9010');
page.screenshot({path: '__image_snapshots__/cra-kitchen-sink-snap.png'});
```


## Pull Requests (PRs)

We welcome your contributions. There are many ways you can help us. This is few of those ways:
Expand Down Expand Up @@ -186,51 +221,95 @@ If an issue is a `bug`, and it doesn't have a clear reproduction that you have p

> If you want to work on a UI feature, refer to the [Storybook UI](https://github.com/storybooks/storybook/tree/master/lib/ui) page.

This project written in ES2016+ syntax so, we need to transpile it before use.
So run the following command:
### Prerequisites

```sh
yarn dev
```
Please have the **_latest_** stable versions of the following on your machine

This will watch files and transpile in watch mode.
- node
- yarn

### Linking
### Initial Setup

First of all link this repo with:
If you run into trouble here, make sure your node, npm, and **_yarn_** are on the latest versions (yarn at least v1.0.0).

```sh
yarn link
```
1. `cd ~` (optional)
2. `git clone https://github.com/storybooks/storybook.git` _bonus_: use your own fork for this step
3. `cd storybook`
4. `yarn`
5. `yarn bootstrap --core`
6. `yarn test --core`
7. `yarn dev` _You must have this running for your changes to show up_

In order to test features you add, you may need to link the local copy of this repo.
For that we need a sample project. Let's create it.
#### Bootstrapping everything

```sh
yarn global add create-react-app getstorybook
create-react-app my-demo-app
cd my-demo-app
getstorybook
```
_This method is slow_

> It's pretty important to create a very simple sample project like above.
> Otherwise some of the functionality won't work because of linking.
1. `yarn bootstrap --all`
2. Have a beer 🍺
3. `yarn test` (to verify everything worked)

Then link storybook inside the sample project with:
### Working with the kitchen sink apps

```sh
yarn link @storybook/react
```
Within the `examples` folder of the Storybook repo, you will find kitchen sink examples of storybook implementations for the various platforms that storybook supports.

Not only do these show many of the options and addons available, they are also automatically linked to all the development packages. We highly encourage you to use these to develop/test contributions on.

#### React and Vue

1. `yarn storybook`
2. Verify that your local version works

### Getting Changes
### Working with your own app

After you've done any change, you need to run the `yarn storybook` command every time to see those changes.
#### Linking Storybook

Storybook is broken up into sub-projects that you can install as you need them. For this example we will be working with `@storybook/react`.
**Note:** You need to `yarn link` from inside the sub project you are working on **_NOT_** the storybook root directory

1. `cd app/react`
2. `yarn link`

#### Connecting Your App To Storybook

**_Note:_** If you aren't seeing addons after linking storybook, you probably have a versioning issue which can be fixed by simply linking each addon you want to use.
This applies for the kitchen sink apps as well as your own projects.
_Make sure `yarn dev` is running_
##### 1. Setup storybook in your project
First we are going to install storyboook, then we are going to link `@storybook/react` into our project. This will replace `node_modules/@storybook/react` with a symlink to our local version of storybook.
1. `getstorybook`
2. `yarn storybook`
3. Verify that your local version works
##### 2. Link
**_Note_**: This process is the same for `@storybook/vue`, `@storybook/addon-foo`, etc
1. Go to your storybook _root_ directory
2. `yarn dev`
3. Wait until the output stops (changes you make will be transpiled into dist and logged here)
4. Go to your storybook-sandbox-app directory
5. `yarn link @storybook/react`
6. `yarn storybook`
#### Verify your local version is working
You should now have a working storybook dev environment up and running. To verify this you can make changes to the following file:
`open app/react/src/client/manager/preview.js`
Save and go to `http://localhost:9009` (or wherever storybook is running)
If you don't see the changes rerun `yarn storybook` again in your sandbox app

## Release Guide

This section is for Storybook maintainers who will be creating releases. It assumes:

- yarn >= 1.0.0 (otherwise you should pass a -- before command arguments)
- yarn >= 1.0.0
- you've yarn linked `pr-log` from <https://github.com/storybooks/pr-log/pull/2>
The current manual release sequence is as follows:
Expand Down Expand Up @@ -294,4 +373,4 @@ npm run publish -- --concurrency 1 --force-publish=*
# update the release page
open https://github.com/storybooks/storybook/releases
```
```

0 comments on commit 1e9538c

Please sign in to comment.