research-hub-web

Research Hub Web

Prod

Test

Dev

Overview

The front end for the Research Hub. Deployed on AWS via Jenkins Pipeline.

Languages/Frameworks:

• Angular
• Angular Material
• Apollo GraphQL

Other Technologies:

• AWS S3: Bucket contains static build files
• AWS CloudFront: S3 assets are distributed via this CDN
• AWS Cognito: Used for user authentication
• Contentful: Headless Content Management System where the site's content is hosted
• Sentry.io: Error and performance monitoring

Local Development

For local development run npm run dev. This will concurrently:

1. Boot up the cer-graphql server locally
2. Generate the schema types/GraphQL services file by introspecting the locally running cer-graphql instance
3. Monitor any changes to the research-hub-web/src/app/graphql/ folder and automatically regenerate the schema types file if any changes are detected
4. Serve the web project locally on port 4200, querying the locally running GraphQL server
5. Run the unit tests, with test-coverage reporting enabled. These unit tests are re-run whenever any files are changed

Alternatively, if you are using VS Code/VSCodium, press F5 to run the above tasks in separate terminals with debugging support enabled, or go to Terminal > Run Task... to see all available tasks.

Testing

This project includes both unit and e2e tests, which can either be run manually, or with an interactive CLI test runner included with the project. Further detail is provided in the corresponding sections below.

Unit Tests

Unit tests are stored in .spec.ts files throughout the project. These can be run with Karma using headless-Chrome in several different ways:

• npm run test/ng test: Runs the unit tests once. The unit test-coverage report is displayed in the CLI
• npm run test-ci: Runs the unit tests once. The unit test-coverage report IS NOT displayed in the CLI. Used in Jenkins
• npm run test-watch: Runs the unit tests continuously (re-runs whenever any files are updated). The unit test-coverage report IS displayed in the CLI
• npm run dev: As mentioned above, this command also executes npm run test-watch
• ./test.sh: The unit tests can also be executed via the Interactive Test Runner

End-to-End Tests

E2E tests are stored in .e2e.js files in /cypress/integration/.

• The tests themselves can be executed against a locally compiled version, or against a remote URL.

The recommended way to execute these tests is via the Interactive Test Runner.

Interactive Test Runner

This project comes bundled with an interactive bash CLI test runner capable of launching your:

• Unit tests
• e2e tests
  • Using Cypress

Simply run ./test.sh to specify what sort of testing you would like to do.

Preview environment

Aside from the main site, a preview version of the site is also built for content authors to view draft articles before they're published. The preview version is identical to the main site aside from content query endpoints. There is a preview environment configuration file for each deployment environment. The files are kept in the src/environments folder, named environment.[DEPLOYMENT ENVIRONMENT]-preview.ts. The files determine where the frontend sends GraphQL content queries, and which requests require authentication.

The monorepo Jenkinsfile runs ng build to build the preview version of the site at the same time as the main site. The script passes the preview configuration file name to build the preview site. Search "preview" in the Jenkinsfile to understand how it's being built in the Continuous Integration process.

See also the README.md files in cer-graphql and terraform folders, and also the monorepo README.md.

GraphQL Schema Types & Services

This project contains an automatically generated schema types/GraphQL services file. This is generated by introspecting a running cer-graphql instance (by default it looks for a locally running instance). This is done with the GraphQL Code Generate Tool.

This generated file contains both:

• TypeScript types corresponding to the GraphQL server's schema
• Angular services automatically generated from any .query.graphql files located in the queries folder.

GraphQL Generator Settings

The GraphQL Generator Tool's settings are controlled via the codegen.yml. Documentation for which can be found here.

Generate new GraphQL schema types

The generator can be executed in several ways:

• npm run generate: Regenerates once and then exits
• npm run generate-watch: Regenerates once, then watches for any changes to .graphql files in the queries folder
• npm run dev: As mentioned in the Local Development Section, this command also executes npm run generate-watch

PWA / Service Worker

This application is a Progressive Web Application (PWA) - an app which behaves like a native app but can be used by devices on various platforms (Android, iOS or desktop). When a user visits the site, they can choose to install it as an app by clicking the install button in the browser bar. PWAs use Service Workers to manage caching and a web app manifest to make it installable. PWAs have enhanced capabilities and reliability over a traditional web app, such as faster loading time and more reliable functionality offline or on slow network connections.

Angular provides a preconfigured service worker that can be added to an existing Angular app using the command ng add @angular/pwa. The command does the following:

• Create a service worker with a default caching configuration.
• Create a manifest file, which tells the browser how your app should behave when installed on the user's device.
• Add a link to the manifest file in index.html.
• Add the theme-color tag to index.html.
• Create app icons in the src/assets directory. Read more info here about Angular service worker and PWA.

Testing PWA / Service Worker locally:

Because ng serve does not work with service workers, you must use a separate HTTP server to test service worker locally. You can use http-server, for example. Install it globally: npm install --global http-server. Now you can run a build of the project (in whichever environment you want to test - e.g. ng build --configuration dev), and then serve the build directory (www) using http-server: http-server -p 8080 -c-1 www. You can now see the service worker information in the browser developer tools. You can run the command npm run start:sw to do the same.

NOTE: not all navigation/redirects will work correctly when serving from the http-server due to the server address and environment settings etc. The best way to test the service worker is to do a proper deployment into the dev environment.