README.md 6.73 KB
Newer Older
1 2
# Passit Front

David Burke's avatar
David Burke committed
3
passit-frontend is the angular client for [Passit](https://passit.io). It includes both the web version and mobile app.
Saul Shanabrook's avatar
Saul Shanabrook committed
4

5 6 7
We use smart and dumb components with ngrx/store.
Read about it [here](https://gist.github.com/btroncone/a6e4347326749f938510#utilizing-container-components)

Saul Shanabrook's avatar
Saul Shanabrook committed
8
API and crypto interaction are handled by passit-sdk-js which itself uses libsodium.js.
David Burke's avatar
David Burke committed
9

David Burke's avatar
David Burke committed
10 11
# Passit Web

12 13 14
## Install Extensions

- [Chrome Web Store](https://chrome.google.com/webstore/detail/passit/pgcleadjbkbghamecomebcdakdmahkeh)
David Burke's avatar
David Burke committed
15
- [Firefox addon](https://app.passit.io/ext/passit.xpi)
16

David Burke's avatar
David Burke committed
17
## Start developing
Cara Clarke's avatar
Cara Clarke committed
18

19
1. Install docker and docker-compose
20
2. Run `docker-compose up`
21

22 23
The front end is now running on localhost:4200 and the backend docker image is running on localhost:8000

David Burke's avatar
David Burke committed
24
Run any one off commands like `docker-compose run --rm web ng` to execute them inside the docker container.
25

David Burke's avatar
David Burke committed
26
You may want to run the client without docker. This is helpful when writing unit tests or for quickly adding packages. If you'd like to do this:
27

David Burke's avatar
David Burke committed
28
1. Start the backend in docker `docker-compose up api`
Emily Jensen's avatar
Emily Jensen committed
29
2. Ensure node 10 and npm are installed?
David Burke's avatar
David Burke committed
30 31 32
3. Install node packages `npm i`
4. Run the frontend `npm start` or use any `npm run ng` command from angular-cli.
5. You can still run the backend with docker using `docker-compose up api`
David Burke's avatar
David Burke committed
33

David Burke's avatar
David Burke committed
34 35 36 37
**Hot Reload**

To enable webpack hot reloading run `npm run hmr` instead of start.

38 39
### Rebuilding when changing package.json

David Burke's avatar
David Burke committed
40
If you need to run `npm i` you'll want to instead run `docker-compose build` and `docker-compose rm -v app` to remove the old container.
41
This is because node_modules are kept in a docker volume.
42

Saul Shanabrook's avatar
Saul Shanabrook committed
43 44
## Running unit tests

David Burke's avatar
David Burke committed
45 46 47 48 49 50 51
Run `npm test` to execute the unit tests via [Karma](https://karma-runner.github.io).

## Running storybook

We write storybook stories for presentational components instead of unit tests. To run:

`npm run storybook`
Saul Shanabrook's avatar
Saul Shanabrook committed
52 53 54

## Running end-to-end tests

55
End-to-end tests are run via [Protractor](http://www.protractortest.org/).
Saul Shanabrook's avatar
Saul Shanabrook committed
56

David Burke's avatar
David Burke committed
57
We'll run the backend in docker and the frontend without for simplicity. Ensure you run `npm` first to install local node modules.
Saul Shanabrook's avatar
Saul Shanabrook committed
58

59
1. Start backend `docker-compose up api`
David Burke's avatar
David Burke committed
60 61
2. Start dev server `npm start`
3. Run test `npm run e2e`
Cara Clarke's avatar
Cara Clarke committed
62

63
The e2e script will use the existing dev server (so you don't have to wait for it to rebuild each time)
Saul Shanabrook's avatar
Saul Shanabrook committed
64

Saul Shanabrook's avatar
Saul Shanabrook committed
65 66
We can also run the e2e tests against firefox, by setting the `FIREFOX` environmental variable to something and we can run them against the web extension
by setting `EXTENSION` env variable to be something (before testing against the extension you have to build it with `build:ext`.
Saul Shanabrook's avatar
Saul Shanabrook committed
67

Saul Shanabrook's avatar
Saul Shanabrook committed
68
We can also run the tests in docker:
69 70

```bash
Saul Shanabrook's avatar
Saul Shanabrook committed
71 72 73
docker-compose up -d app selenium-<chrome/firefox>
[docker-compose run app build:ext]
docker-compose run [-e FIREFOX=true] [-e EXTENSION=true] app e2e:docker
74
```
Saul Shanabrook's avatar
Saul Shanabrook committed
75

David Burke's avatar
David Burke committed
76
### end-to-end test structure and how to
Natalie Liles's avatar
Natalie Liles committed
77

David Burke's avatar
David Burke committed
78 79
We ensure that each `describe` block can be run in any order.
However each `it` step inside a block actually must run in order - as to minimize set up time which is time consuming due to expensive crypto functions being used when logging in.
Natalie Liles's avatar
Natalie Liles committed
80

81 82 83
- The `describe` blocks do not need to run in order.
- Each `describe` block creates a new user.
- Some `it` statements within a `describe` block depend on state from previous tests and need to run in order.
David Burke's avatar
David Burke committed
84 85

New users are created in the docker backend with random user names to prevent collisions. This means we don't have to wipe the backend between tests which also saves time (at the expense of this being slightly ugly).
Natalie Liles's avatar
Natalie Liles committed
86

87
## Coding Style and Linting
David Burke's avatar
David Burke committed
88

David Burke's avatar
David Burke committed
89
Follow style and design patterns as seen on the [ngrx example-app](https://github.com/ngrx/platform/tree/master/projects/example-app) and from angular-cli.
Cara Clarke's avatar
Cara Clarke committed
90

91
```bash
David Burke's avatar
David Burke committed
92
npm run lint
93 94
```

95 96 97 98 99 100
### Error handling

Error and validation can get complex. We have the backend API, js SDK, services, and effects as potential sources of errors. Here are some guidelines:

- Do use ngrx-forms's client side validation
- Only use ngrx-forms async validation for "as you type" server side validation. Do not use it for server errors.
David Burke's avatar
David Burke committed
101 102
- Services should handle errors and return an Observable. They should throw handled error messages as an error.
- Effects should connect services to the correct action response. Effects are glue code and should avoid complex logic (which should be in a service).
103

104
## Development for web extension
David Burke's avatar
David Burke committed
105 106 107 108 109 110 111 112

The web extension works in Firefox and Chrome. It reuses the same angular code but we need to build it differently.

For development:

We'll run this time without docker (though you could use docker). We want to build the app with aot and watch enabled for auto reload.
Then we'll run web-ext to launch the code as an extension in Firefox.

David Burke's avatar
David Burke committed
113
1. Run backend either in docker (`docker-compose up api`) or hosted service
114 115 116
2. `npm install` (if not done already)
3. `npm run build:ext -- --watch`
4. (new term) For Firefox `npm run ext:run` and for Chrome go to `dist/manifest.json` and change `"CI_INSERT_VERSION_HERE"` to a number. Change `"content_security_policy": "script-src 'self'; object-src 'self'",` to `"content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self'",`. (Make sure you do not commit these changes in the manifest.json file.) Open Chrome and go to `chrome://extensions/`. Ensure Developer mode is checked. Click Load unpacked and select the dist folder that is generated by the npm run build:ext step.
David Burke's avatar
David Burke committed
117 118

Because the app shares the same code, going to routes like `/popup` actually work fine in the web version. However note when not
119 120
running as an extension you won't have access to web extension api's like the browser object.

121 122
### Autofill development

David Burke's avatar
David Burke committed
123
Autofill code is injected into the page. It must be compiled.
124 125

1. Remove `export` from `extension/form-fill/form-fill.ts`
David Burke's avatar
David Burke committed
126
2. Compile with `npm build:autofill`
127 128
3. Copy and paste the resulting js file into autofill-compiled.ts as a string.

David Burke's avatar
David Burke committed
129 130
# Mobile app

David Burke's avatar
David Burke committed
131 132 133 134 135 136 137 138 139 140 141
Passit's mobile app runs via Nativescript. It uses a mono-repo approach described [here](https://docs.nativescript.org/angular/code-sharing/intro)
Basically a file like something.tns.ts will replace the web version of that file.

## Install

1. Install Nativescript [See instructions for Linux](https://docs.nativescript.org/start/ns-setup-linux)
2. Ensure `tns doctor` runs.
3. Set up an emulator or physical device.

## Running

David Burke's avatar
David Burke committed
142
Run `tns run android --bundle` or `tns run android --hmr` for hot reloading.
David Burke's avatar
David Burke committed
143 144 145

** Troubleshooting **

David Burke's avatar
David Burke committed
146
- Delete node modules and generated resources `rm -rf hooks platforms node_modules` then `npm i`
David Burke's avatar
David Burke committed
147
- Force a new apk build `tns build android`
148 149 150

### Technologies used

151 152 153
- [Angular](https://angular.io/) with [TypeScript](http://www.typescriptlang.org/) and [ngrx/platform](https://github.com/ngrx/platform/)
- [NativeScript](https://www.nativescript.org/) for mobile
- [libsodium.js](https://github.com/jedisct1/libsodium.js) for crypto with good defaults