environment setup

Install NodeJS.

This app runs on NodeJS, we recommend using mise to manage the node version.

mise use node@lts

Install project dependencies

npm install

Generate the evolver-ng typescript client

1. from the /evolver-ng repo generate an openapi.json file and copy it into this, project's root directory.

tox -e generate_openapi

2. from the /evolver-ui directory run this command.

npm run bootstrap_evolver_ts_client

Development

Setup env variables

cp .env.example .env

Setup dev db

npx prisma migrate dev --name init

If you adapt the schema run this command again to generate migrations that will be applied to the prod db.

Run the dev server against the dev db

Run the dev server:

npm run dev

Deployment

This app can run on an evolver device (raspberry pi). It can also run persistently in the cloud or on a local machine in your lab. This app can connect to an unlimited number of evolver devices.

build the web app

npm run build

run the web app:

npm start

dependency documentation

database - used to store the devices you've connected to

sqlite - the prisma ORM handles database management (schema, migrations, etc...).

orm - to manage the db

Prisma ORM

framework - a reference implementation demonstrating the capabilities of the evolver's HTTP API.

Remix - a fullstack framework, it consists of a Node.js based server, tightly coupled to a react web app through the use of HTTP web standards and react hooks. React - a frontend framework Tailwind - a css styling framework DaisyUI - a component library for tailwind, that simplifies composing tailwind classnames by providing generic defaults.

testing

unit tests

npm run test

Vitest and react-testing-library are used for unit tests, if a system entity is pure (this term is generally analagous to idempotency) it is a good candidate for unit tests. For example a React component that is a pure function of it's parameters/props. Or remix loaders and actions that are a pure function of the parameters of the incoming request that they handle.

integration tests

npm run test:integ

Whenever a part of the system relies on network requests or complex user interactions, we consider it impure, in these cases, it has dependencies outside our control. For example network requests fail, or respond with unexpected data, while user interactions introduce cyclomatic complexity. To cover these cases we rely on MSW and puppeteer respectively to encapsulate and manage the complexity introduced by the network boundary and human interaction. Within the context of this app, remix routes are a good candidate for integration tests.

Having trouble with MSW? Refer to this example repo: https://github.com/mswjs/examples/blob/main/examples/with-remix/README.md

balancing unit and integration tests

remix-run/remix#5769 (comment)

e2e tests

in a production system at scale the entire evolver system, would have a simulated and tested as part of its deployment pipeline as close to production as possible. At this stage e2e tests could be run against real hardware. This is out of scope for current stage of research. e2e tests are not included in this software. That said, the front end integration tests could be run without MSW against a real evolver endpoint to achieve this whenever it becomes necessary.