README.md
1<!-- START doctoc generated TOC please keep comment here to allow auto update -->
2<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
3**Table of Contents**
4
5- [Vault UI](#vault-ui)
6 - [Prerequisites](#prerequisites)
7 - [Running / Development](#running--development)
8 - [Code Generators](#code-generators)
9 - [Running Tests](#running-tests)
10 - [Automated Cross-Browser Testing](#automated-cross-browser-testing)
11 - [Running Browserstack Locally](#running-browserstack-locally)
12 - [Linting](#linting)
13 - [Building Vault UI into a Vault Binary](#building-vault-ui-into-a-vault-binary)
14 - [Vault Storybook](#vault-storybook)
15 - [Storybook Commands at a Glance](#storybook-commands-at-a-glance)
16 - [Writing Stories](#writing-stories)
17 - [Adding a new story](#adding-a-new-story)
18
19<!-- END doctoc generated TOC please keep comment here to allow auto update -->
20
21# Vault UI
22
23This README outlines the details of collaborating on this Ember application.
24
25## Prerequisites
26
27You will need the following things properly installed on your computer.
28
29- [Node.js](https://nodejs.org/) (with NPM)
30- [Yarn](https://yarnpkg.com/en/)
31- [Git](https://git-scm.com/)
32- [Ember CLI](https://ember-cli.com/)
33- [Husky\*](https://github.com/typicode/husky)
34- [lint-staged\*](https://www.npmjs.com/package/lint-staged)
35
36\* Husky and lint-staged are optional dependencies - running `yarn` will install them.
37If don't want them installed (husky adds files for every hooks in `.git/hooks/`),
38then you can run `yarn --ignore-optional`. If you've ignored the optional deps
39previously and want to install them, you have to tell yarn to refetch all deps by
40running `yarn --force`.
41
42## Running / Development
43
44To get all of the JavaScript dependencies installed, run this in the `ui` directory:
45
46- `yarn`
47
48If you want to run Vault UI and proxy back to a Vault server running
49on the default port, 8200, run the following in the `ui` directory:
50
51- `yarn run start`
52
53This will start an Ember CLI server that proxies requests to port 8200,
54and enable live rebuilding of the application as you change the UI application code.
55Visit your app at [http://localhost:4200](http://localhost:4200).
56
57If your Vault server is running on a different port you can use the
58long-form version of the npm script:
59
60`ember server --proxy=http://localhost:PORT`
61
62### Code Generators
63
64Make use of the many generators for code, try `ember help generate` for more details
65
66### Running Tests
67
68Running tests will spin up a Vault dev server on port 9200 via a
69pretest script that testem (the test runner) executes. All of the
70acceptance tests then run, proxing requests back to that server.
71
72- `yarn run test-oss`
73- `yarn run test-oss -s` to keep the test server running after the initial run.
74- `yarn run test -f="policies"` to filter the tests that are run. `-f` gets passed into
75 [QUnit's `filter` config](https://api.qunitjs.com/config/QUnit.config#qunitconfigfilter-string--default-undefined)
76- `yarn run test:browserstack` to run the kv acceptance tests in Browserstack
77
78#### Automated Cross-Browser Testing
79
80Vault uses [Browserstack Automate](https://automate.browserstack.com/) to run all the kv acceptance tests on various browsers. You can view the list of browsers we test by viewing `testem.browserstack.js`.
81
82##### Running Browserstack Locally
83
84To run the Browserstack tests locally you will need to add your `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` to your environment. Then run `yarn run test:browserstack`. You can view the currently running tests at `localhost:7357` or log in to [Browserstack Automate](https://automate.browserstack.com/) to view a previous build.
85
86To run the tests locally in a browser other than IE11, swap out `launch_in_ci: ['BS_IE_11']` inside `testem.browserstack.js`.
87
88### Linting
89
90- `yarn lint:hbs`
91- `yarn lint:js`
92- `yarn lint:js -- --fix`
93
94### Building Vault UI into a Vault Binary
95
96We use `go-bindata-assetfs` to build the static assets of the
97Ember application into a Vault binary.
98
99This can be done by running these commands from the root directory run:
100`make static-dist`
101`make dev-ui`
102
103This will result in a Vault binary that has the UI built-in - though in
104a non-dev setup it will still need to be enabled via the `ui` config or
105setting `VAULT_UI` environment variable.
106
107## Vault Storybook
108
109The Vault UI uses Storybook to catalog all of its components. Below are details for running and contributing to Storybook.
110
111### Storybook Commands at a Glance
112
113| Command | Description |
114| ------------------------------------------ | ------------------------- |
115| `yarn storybook` | run storybook |
116| `ember generate story [name-of-component]` | generate a new story |
117| `yarn gen-story-md [name-of-component]` | update a story notes file |
118
119### Writing Stories
120
121Each component in `vault/ui/app/components` should have a corresponding `[component-name].stories.js` and `[component-name].md` files within `vault/ui/stories`.
122
123#### Adding a new story
124
1251. Make sure the component is well-documented using [jsdoc](http://usejsdoc.org/tags-exports.html). This documentation should at minimum include the module name, an example of usage, and the params passed into the handlebars template. For example, here is how we document the ToggleButton Component:
126
127````js
128/**
129 * @module ToggleButton
130 * `ToggleButton` components are used to expand and collapse content with a toggle.
131 *
132 * @example
133 * ```js
134 * <ToggleButton @openLabel="Encrypt Output with PGP" @closedLabel="Encrypt Output with PGP" @toggleTarget={{this}} @toggleAttr="showOptions"/>
135 * {{#if showOptions}}
136 * <div>
137 * <p>
138 * I will be toggled!
139 * </p>
140 * </div>
141 * {{/if}}
142 * ```
143 *
144 * @param toggleAttr=null {String} - The attribute upon which to toggle.
145 * @param attrTarget=null {Object} - The target upon which the event handler should be added.
146 * @param [openLabel=Hide options] {String} - The message to display when the toggle is open. //optional params are denoted by square brackets
147 * @param [closedLabel=More options] {String} - The message to display when the toggle is closed.
148 */
149````
150Note that placing a param inside brackets (e.g. `[closedLabel=More options]` indicates it is optional and has a default value of `'More options'`.)
151
1522. Generate a new story with `ember generate story [name-of-component]`
1533. Inside the newly generated `stories` file, add at least one example of the component. If the component should be interactive, enable the [Storybook Knobs addon](https://github.com/storybooks/storybook/tree/master/addons/knobs).
1544. Generate the `notes` file for the component with `yarn gen-story-md [name-of-component]` (e.g. `yarn gen-md alert-banner`). This will generate markdown documentation of the component and place it at `vault/ui/stories/[name-of-component].md`. If your component is a template-only component, you will need to manually create the markdown file.
155
156See the [Storybook Docs](https://storybook.js.org/docs/basics/introduction/) for more information on writing stories.
157
158### Code Generators
159
160It is important to add all new components into Storybook and to keep the story and notes files up to date. To ease the process of creating and updating stories please use the code generators using the [commands listed above](#storybook-commands-at-a-glance).
161
162
163## Further Reading / Useful Links
164
165- [ember.js](http://emberjs.com/)
166- [ember-cli](https://ember-cli.com/)
167- Development Browser Extensions
168 - [ember inspector for chrome](https://chrome.google.com/webstore/detail/ember-inspector/bmdblncegkenkacieihfhpjfppoconhi)
169 - [ember inspector for firefox](https://addons.mozilla.org/en-US/firefox/addon/ember-inspector/)
170- [Storybook for Ember Live Example](https://storybooks-ember.netlify.com/?path=/story/addon-centered--button)
171- [Storybook Addons](https://github.com/storybooks/storybook/tree/master/addons/)
172- [Storybook Docs](https://storybook.js.org/docs/basics/introduction/)
173- [Browserstack Automate](https://automate.browserstack.com/)
174