Add more documentation

Author: Jason Laster

README.md

@@ -54,9 +54,7 @@ As a developer, you most likely want to enable hot reloading. This means you can
 * `npm run cypress-intermittents` - Runs tests 100 times and writes the output to cypress-run.log
 * `cypress open` - Run tests in the browser
 
-**Notes:**
-* Firefox needs to be open and listening on port 6080 before the tests are run. You can start Firefox on the right port with this command `npm run firefox`.
-* Cypress needs to be installed before tests can be run. When you run cypress the first time, you will be prompted to install it. `cypress install`.
+[More information](./docs/integration-tests.md).
 
 ### Linting
 * `npm run lint` - Run CSS and JS linter
@@ -67,7 +65,7 @@ As a developer, you most likely want to enable hot reloading. This means you can
 * `npm run test-all` - Run unit tests, lints, and integration tests
 
 ### Storybook
-* `npm run storybook` - Open Storybook
+* `npm run storybook` - Open Storybook. [more info](./docs/local-development.md#storybook)
 
 ## Configuration
 
@@ -77,6 +75,8 @@ You can see default config values in `config/development.json`, and override the
 * `chrome.debug` enable local chrome development
 * `features.sourceTabs` enable editor tabs
 
+[More Information](./docs/local-development.md#configs)
+
 ## Misc
 
 ### Enabling remote debugging in Firefox

docs/integration-tests.md

@@ -0,0 +1,74 @@
+## Integration Tests
+
+Debugger.html integration test are end-to-end tests that simulate a user debugging an application.
+
+The tests open two browser tabs, the debuggee and debugger, and go through the steps of debugging the debuggee.
+
+Here's one test that pauses while creating a Todo.
+
+```js
+debugPage("todomvc");
+goToSource("js/views/todo-view");
+toggleBreakpoint(33);
+
+addTodo();
+
+stepIn();
+stepOver();
+stepOut();
+```
+
+#### Helpful Information
++ `public/js/test/integration` - tests folder
++ `public/js/test/cypress/commands` - test commands folder
+
+#### Running tests
++ `npm run firefox` - launch firefox
++ `cypress run` - runs tests headlessly
++ `cypress open` - opens cypress app
+
+**Installing Cypress**
+Cypress needs to be installed before tests can be run.
+
+```bash
+npm install -g cypress-cli
+cypress install
+```
+
+[More Information](https://docs.cypress.io/docs/installing-and-running)
+
+Notes:
++ It's helpful to close the firefox debugger in other tabs as it might cause the tests to miss a firefox message.
++ You can also test chrome by opening chrome and enabling the chrome test in `todomvc.js`.
+
+#### Cypress
+
+The Debugger.html project uses [Cypress](https://www.cypress.io/) for integration tests.
+
+**Features**
+
++ [Commands](https://docs.cypress.io/docs/issuing-commands) that interact with the app (click, type, ...)
++ [Selectors](https://docs.cypress.io/docs/finding-elements) that wait for elements to be available (get, contains)
+
+**Pro Tips**
++ `it.only` - will only run that test
++ `file watching` - cypress re-runs tests on file changes.
+
+#### Fixtures
+
+We use Cypress to generate the fixtures that are used in the unit tests and storybook stories.
+
+[Fixtures](../public/js/test/integration/fixtures.js) are written like other integration tests, with an extra step for saving a fixture.
+
++ `public/js/test/integration/fixtures.js` - fixtures file
++ `public/js/test/fixtures` - Fixture folder
+
+Steps:
++ start the cypress server to save the fixtures - `node bin/cypress-server`
++ enable the fixture tests - change `xdescribe` to `describe` in [fixtures.js](../public/js/test/integration/fixtures.js).
++ run cypress - `cypress run`
+
+
+#### Screenshots
+
+![](./screenshots/cypress-runner.png)

docs/local-development.md

@@ -0,0 +1,56 @@
+## Local Development
+
+The easiest way to get started debugging firefox is with these two commands.
+
+```bash
+`npm run firefox`
+`npm start`
+```
+
+### Development Server
+
+The development server does many things to help make local development easier.
+
++ uses webpack to bundle the debugger js and css assets
++ uses webpack-express-middleware to update the bundle on page refresh
++ can enable hot reloading for react components and css
++ starts the firefox proxy, which passes messages between the debugger and debugged firefox browser.
++ builds the set of environment and user config for the debugger.
++ gets the list of chrome tabs that can be debugged.
+
+### Configs
+
+There are a couple types of configs for the debugger:
+
++ Feature flags - that can turn on/off experimental features
++ Development flags - features like hot reloading or logging that can make it easier to develop
++ Configuration - settings like the firefox websocket port, which set global configuration data.
+
+**Local Configs**
+
+You can easily override values locally for your own environment or development preferences.
+
+Local changes go in a `local.json` file in config next to `development.json`.
+If that file does not exist, copy `local.sample.json`.
+
+### Hot Reloading
+
+Hot reloading lets you make changes in React components and CSS and see the changes immediately.
+Also, the changes will go into effect without changing the state of app.
+Hot reloading does not work all the time, but once you get a sense of its quirks it can be a huge productivity boon.
+
+It can be turned on by setting `config/local.json` with the contents `{ "hotReloading: true" }`.
+
+### StoryBook
+
+Storybook is a local development environment for react components for viewing components in different states.
+
+**Features:**
++ toggle between different UI states
++ quickly work on a component with hot reloading
+
+**Getting Started:**
++ start storybook `npm run storybook`
++ edit a component story in `public/js/components/stories`
+
+![](./screenshots/storybook.png)