Skip to content

Latest commit

 

History

History
350 lines (210 loc) · 12.3 KB

README.md

File metadata and controls

350 lines (210 loc) · 12.3 KB
Raw

App

Web application sample project.

Requirements

  • GNU make
  • docker
  • npm
  • Cypress desktop app; 10.8.0+ (optional)

Cypress setup (optional; for test based development)

If you want to use Cypress as a desktop application (which it really is!), you need to separately install it on your system. This use is recommended, in the longer term, because it offers a great developer experience.

For now, you can skip these installation instructions and return back here, once/if you wish to give Desktop Cypress a go!

Note: Cypress is also used in this repo for automatically running front-end tests. For this, you don't need to do further installs.

To install Cypress:

macOS
  • Visit Installing Cypress > Direct download
    • download cypress.zip
  • unzip it
  • move Cypress.app to a destination of your liking, e.g. the user specific Applications folder.
  • launch Cypress.app
Linux

There is no dedicated desktop download for Linux. Instead, you need npm (or some other Node.js package manager) to install it.

Follow instructions at Installing Cypress > Linux Prerequisites:

$ sudo apt-get update
$ sudo apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb

Then:

$ npm install -g cypress
$ npx cypress open
Windows 10 + WSL2

See DEVS/Interactive Cypress with X410 for details.

Updating Cypress..

Once there are more recent versions available, you'll see it in the Cypress GUI:

You'll see the changes by clicking See all releases, before updating.

This feature does not support the "direct download" route of installing that we took, but requests you to use npm, instead. You can, however, use it to be informed of new versions. If you want to upgrade, repeat the installation above.

Getting started

$ make install

Launch the app

$ make dev
...

  VITE v3.2.0-beta.2  ready in 690 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: http://172.20.0.2:3000/

...

This serves the UI locally, against an emulated Firebase back-end.

Try it:

http://localhost:3000?user=dev

Within local mode, you sign in by ?user=dev query parameter.

Make some changes in the src/** files and see that they are reflected in the browser.

Note: The IP (172.20.0.2) mentioned above exists only within the Docker container. Ignore it.

Two development workflows

The above command started a local, emulated version of Firebase.

The other way is make dev:online. This works against your cloud Firebase project. We'll come to it shortly.

Differences of these modes:

Back-end Data Users Authentication Central logging
local emulated primed from local/docs.js primed from local/users.js with &user=<id> To emulated Realtime Database only
online in the cloud in the cloud; changes are persistent ← against real accounts Via online Realtime Database to Grafana Cloud; stage "{stage-id}", release ""

For local mode, the priming happens anew at each Docker Compose launch.

Note: Tests (make test) use the same Docker Compose service as local mode, but bring their own data and users. You can use both make dev and make test at the same time. The two use different Firebase project id's so their data and users won't overlap.

dev[:local]

Use this mode when:

  • you are developing back-end features (Firestore security rules, Cloud Functions) and want to test that they work with the front-end.
  • you want to start with primed data and users, each time, instead of persisting the changes
  • you want to skip the sign-in dialog, to speed up development a few clicks
  • you don't have a Firebase account, yet

With local mode, you can test back-end features while developing them, and only commit stuff that works.

dev:online

With "online" development, you run against the Firebase back-end services, but still have hot-module-reload to help in developing the UI.

Use this when:

  • the back-end is stable, and you are working on UI features
  • the back-end is deployed
  • you don't mind actually changing data
  • you have a Firebase account
  • you want to sign in as a real user

The mode needs firebase.staging.js in the project's root, to find the staging project. This will be created during your first deployment.

Note: You can choose another project by ENV=abc make dev:online.

Launch! 🚀

Launch the server:

$ make dev:online
...

Point your browser to http://localhost:3001.

Changes to your front-end files are still reflected in the browser, but back-end services are now run in the cloud. Changes you do to the data will persist. Metrics and logs are proxied to Grafana Cloud (if you have set it up). Traffic you create will be using your Firebase quotas.

The two development modes are completely orthogonal - you can run them side by side, in different terminals.

Linting

Before we look at tests, a brief mention on linting.

$ make dev:lint
...

This gives you warnings that you may or may not wish to fix. Steer them at .eslintrc.cjs.

Note: At the moment (Apr 2021 Oct 2022) we're not focused on reducing the number of lint warnings.

Testing

You can use Cypress for running all the tests at once from the command line, or run them one by one, in a desktop Cypress installation.

For running from command line, Cypress is brought in via Docker Compose and you don't need to do any installs. For test based development, a desktop application is used. Instructions for setting it up are above ("Requirements" section).

Running all the tests

$ make test

This runs all the front-end tests and returns you back to the OS prompt.

Note: make test runs things within Docker Compose. Building the Cypress image takes some time, the first time the command is launched.

Test based development

The other way is to keep make dev running, and edit both one's code, tests and potentially backend Security Rules, while keeping an eye on the test results. Every time you do a change to the app sources or Cypress tests, Cypress automatically refreshes the test output.

Have make dev running in a terminal.

Launch Cypress and pick the packages/app subfolder.

  • Choose E2E testing

    • Choose any browser (depends on what you have installed on your computer).

Try to run the tests.

As you can see in the image, always keep the developer tools open while running Cypress tests. It helps.

Note: It seems, with Cypress 10 there is no longer a "Run all tests" option in the dashboard. That's a shame (so you'll end up make testing for seeing what fails, and drilling into it here).

Now edit some test in the IDE (they are under cypress/e2e).

Cypress will automatically re-run tests while you make changes to the source - or the tests. A big display becomes useful, here!

In short, you can:

  • time travel to see what the UI looked, at the time the tests were executed. (hover over the test steps)
    • pin your view to a particular step in time, by clicking on it
  • Use the regular browser tools to inspect components, see the console etc. also within a time-travelled render!

The Cypress approach changes the way we do software. The more time you spend with it, the more time it likely will save you.

Note: Some Cypress features like "stubs" and "proxies" are not need, at all. Those are intended for building scaffolding when running things locally, but we have the whole Firebase emulators so we can work against the Real Thing.

Manual testing on other devices

Both make dev and make dev:online expose their ports to all network interfaces, within your computer.

This means, the web app is browsable also from a phone, tablet etc. in the same network. All you need is to find out the outwards-facing IP number of your computer (let's say it's 192.168.1.62), and open http://192.168.1.62:3000 (or 3001) from your other device.

Finding your IP number

OS Steps
macOS Preferences > Network > (adapter) > IP address
macOS (terminal) ifconfig
Windows 10 + WSL2 ip route | grep default

Hint: For WLAN on macOS, you can also Alt-click the WLAN icon in the toolbar.

Not quite enough!! Windows 10 + WSL2

The above is not sufficient for WSL2. You'll need to dig a bit deeper, starting e.g. with Running a public server from WSL 2 (blog, Apr 2020).

This author didn't get the sharing to work, but didn't try very hard, since it's not his use case. Please chime in if you get it to work!!

Production build

$ make build
...
vite v3.0.0-beta.9 building for production...
✓ 197 modules transformed.
../dist/index.html                         1.51 KiB
../dist/aside-keys.42ab51fe.js             14.01 KiB / gzip: 5.86 KiB
../dist/aside-keys.42ab51fe.js.map         44.04 KiB
...
../dist/firebase-firestore.1ecd9c81.js     464.63 KiB / gzip: 111.93 KiB
../dist/firebase-firestore.1ecd9c81.js.map 1140.85 KiB

This builds your front end application in dist/ folder.

Hint. We also use rollup-plugin-visualizer to provide a browsable report of the modules. Check it out by opening stats.html.

First deployment

Next, you should take your project to the cloud. While regular updates are intended to be done using CI/CD, you can do your first deployment more manually. Head to /first/README.md for instructions.

After you have completed that, make dev:online will work.

Next steps...

You can now start developing your own application - both backend and front-end.

When you feel like it, take a look at the following folders that have information about managing the application's full lifecycle:

  • /ci - Continuous Integration, using Cloud Build

    You set up the cloud to track changes to your version control, so that code changes get automatically tested and deployed.

  • /ops - Operational monitoring, using Grafana Cloud

    Learn about how to see metrics and logs of your web application, so you can fine tune it - and the users' experience.

  • UPCOMING: /momentum - How to gain users and form a community to support your web app.

This concludes the web app feedback loop. Be your bugs be few, and users delighted!