allegory-of-the-cave

Allegory-of-the-Cave (AOTC)

Allegory-of-the-Cave is kind of a projector 2.0

First a beamer, next a projector, next shadows on a wall - Unknown Author

The Projector is used to provide a proper tooling for project staffing inside of INNOQ. It allows to manage project options and assignments of the INNOQ (or even external) colleages to the options. Additionally it provides a convenient overview of colleages being or becoming available for new projects and similar helpful information for the staffing process.

Why a new Projector?

The Allegory-of-the-Cave project intends to replace the Projector project in the future to provide a more stable and maintainable project. The old Projector has only an implicit understanding of permissions and roles. In the AOTC project there is an explicity permission setup, that helps to reduce glitches and helps the project to be GDPR compliant.

Additionally we try to make the app easier to improve for the staffing process without the constant fear of creating regressions in the rest of the feature base.

Usage

Prerequisites

Dev Database

The project is based on neo4j, so as a prerequisite you need a dev database. You can run e.g. the integration tests npm run test:integration, and spin the db up afterwards to have one in place pretty easily:

docker-compose -p aotc-int -f docker-compose.yml -f docker-compose.int.yml up neo4j
# `use docker-compose -p aotc-int down` to tear the db down if you don't need it anymore

env.yaml

In the env.yaml you can manipulate the ENV vars for the running application. Use the env.template.yaml as a starting point. The env.yaml file is listed in the .gitignore file, so that any dev can make own adjustments there.

cp env.template.yaml env.yaml

If you use the integration db as described above, just point the DB_URL: to the port, the db is running.

install dependencies and start the app

npm install
npm start
# yay :)

or

npm install
npm run watch:start

If you want to tinker around with the code.

Authentication

Visit the URL provided by the console output (e.g. http://localhost:5001). Once you do that you are usually greeted by "You're not logged in or your user is ambiguous".

You have to provide a custom Header REMOTE_USER to gain access to the page. Please give a look to the fixtures loaded to the DB to check which usernames are accessible.

E.g. provide

REMOTE_USER=jane_admin

Development

Run the tests

To be able to run all the tests, you need to have a proper docker setup in place. The tests are using docker-compose to spin up the test databases and applications, run fixture migrations, etc. After having that in place, just go for the package dependencies and run the tests.

npm install
npm test

As the complete test cycle takes some time, and you don't probable need it all the time it is possible to run the tests seperately.

Unit tests

npm run test:unit

done.

Integration tests

For the integration tests it is necessary to load the fixtures before running the tests. All that is bundled in tests/scripts/run-integration-tests.js. Just call for

npm run test:integration

to run the spin up the database, load the fixtures and run the integration tests from within the app container.

Acceptence tests

As for the integration tests for the acceptance tests there is the bundled way of loading fixtures, spinning up the database and app, and running the tests from a separate container against the running app. Just run npm run test:acceptance for that.

To run single scenarios, you can tag them:

@mytag
Scenario: As a xxx I want to ...
 ...

And test only the scenarios that are tagged, with providing an ENV var:

CUCUMBER_FILTER_TAGS="@mytag" npm run test:acceptance

Fixture Import

The test setup relies heavily on a convenient tool to import data into neo4j, the neo4j-admin import, see the (docs)[https://neo4j.com/docs/operations-manual/current/tutorial/neo4j-admin-import/]. It can import CSV files, provided in a certain structure of header and content files. As neo4j is a graph-database there are to kinds of content files, nodes and relationships. The fixture files for the integration and acceptance tests are provided in the format for the import CLI, so we can rely in the test setup on the free import tool.