Inventory Frontend

This is the frontend application for Inventory. It is based on the insights-frontend-starter-app.

Table of contents

• Getting started
  • Quick start
  • Running locally
• Testing
  • Unit testing
  • E2E testing: Playwright
    • First time setup
    • Running Playwright tests
  • Integration Testing: Federated Modules
• Commit conventions
• Testing federated modules with another application
• Mocking Inventory API
• Inventory table and detail
  • Applications using InventoryTable
• Component documentation
• Release process
  • Latest image and Stage deployment
  • Pre-promotion verification
  • Promoting to production
  • Post-release verification
• Common Problems You Might Encounter

Getting started

Quick start

1. Make sure you have Node.js (current LTS) and npm installed.
2. Run script to patch your /etc/hosts.
3. Make sure you are using Red Hat proxy.

Running locally

1. Clone the repository.
2. Install dependencies with npm install.
3. Run development server with npm run start:proxy. See dev.webpack.config.js and package.json (npm scripts) for more options and parameters available.
4. Local version of the app will be available at https://stage.foo.redhat.com:1337/insights/inventory/. If you run with slightly different setup (for example, using production environment), you should still see the generated URL in your terminal, the webpack script output.

Testing

Before running functional tests, ensure your code is type-safe. You can run npm run type-check to verify this.

Unit testing

We use Jest with React Testing Library to write unit tests. For larger pieces of code or components, we utilize Cypress. For testing commands shortcuts (like npm run test, npm run test:ct, etc.), take a look at the package.json file which lists available scripts.

Before opening a pull request, you can run npm run verify:local to make sure your changes pass automated tests (Jest and Cypress) and linter (both JS and CSS linters). We also execute husky hooks with every commit to make sure the changes pass basic lint checks.

E2E testing: Playwright

The E2E tests are located in the _playwright-tests/ directory. playwright.config.js is playwright configuration file - it serves as the "brain" for an automated testing suite, defining how, where, and with what settings your browser tests should run. All the helpers live in the helpers directory.

First time setup

1. Copy the example env file (playwright_example.env) and create a file named .env. For local development only the BASE_URL - https://stage.foo.redhat.com:1337 is required, which is already set in the example config. You also need to set the PLAYWRIGHT_USER and PLAYWRIGHT_PASSWORD for your Stage testing account in the .env file.

2. Install the test runner:

npm install --save-dev @playwright/test

3. Install Playwright browsers and dependencies:

npx playwright install

OR

If using any OS other than Fedora/RHEL (i.e., Mac, Ubuntu Linux):

npx playwright install  --with-deps

Running Playwright tests

1. Start the local development stage server by running: npm run start:stage

2. Use the following commands to execute the Playwright test suite:

• npx playwright test - run the complete playwright test suite
• npx playwright test --headed - run the complete suite in a vnc-like browser so you can watch its interactions
• npx playwright test test_navigation.test.ts - run a specific test file
• npx playwright test test_navigation.test.ts -g "Test name" - run a specific test by its name
• npx playwright test --grep-invert @integration - run tests except integration tests

For more examples on how to run and debug tests, visit the official Playwright documentation.

Integration Testing: Federated Modules

Integration tests ensure our federated modules work correctly within Lightspeed applications at runtime. Run these whenever you modify components shared across services to prevent breaking downstream consumers: npx playwright test --grep @integration

Commit conventions

In order to keep our commits style consistent and the commits history easy to read, we utilize semantic-release which follows Angular Commit Message Conventions. Also, there is a commitlint check run on all branches which ensures that all the commits meet the expected format (<type>(<scope>): <short summary>). Following this standard and specifying at least the type and summary for each commit helps to automatically generate a changelog of changes.

Testing federated modules with another application

If you want to test federated modules (such as InventoryTable or SystemDetail) in another application, you can utilise LOCAL_APPS environment variable and deploy the needed application on separate ports. To learn more about the variable, see https://github.com/RedHatInsights/frontend-components/tree/master/packages/config#running-multiple-local-frontend-applications.

Example

We'll take for example insights-advisor-frontend.

Open new terminal, navigate to Advisor repository, and run it on a separate port without proxy:

npm run start -- --port=8003

In a separate terminal, run Inventory with proxy enabled and list Advisor:

LOCAL_APPS=advisor:8003~http npm run start:proxy

Mocking Inventory API

This is one of the advanced methods to test frontend locally without waiting for API to have desired endpoints available.

Inventory frontend has support for https://github.com/stoplightio/prism CLI. The CLI reads the OpenAPI schema, spins up a localhost server and serves dynamically generated responses for Inventory API endpoints (/hosts, /groups, etc.).

1. Verify package.json config section for the correct URL to OpenAPI schema (contains remote URL by default).
2. Verify dev.webpack.config.js customProxy settings. There you can specify which endpoints to proxy and modify request/response headers.
3. Run npm run mock-server to start the mock server. The first output must list the endpoints that are generated by the localhost server.
4. In another terminal, run npm run start:mock or npm run start:mock:beta to start the webpack server either in stage-stable or stabe-beta environment. The scripts set the MOCK variable to true and the customProxy is enabled.

Inventory table and detail

We are serving inventory through federated modules, this means both inventory table and inventory detail is served to you in runtime. No need to install and rebuild when something changes in inventory.

Applications using InventoryTable

These applications import InventoryTable component through federated modules:

• vulnerability-ui
• insights-remediations-frontend
• sed-frontend
• tasks-frontend
• compliance-frontend
• patchman-ui
• malware-detection-frontend
• ros-frontend
• insights-advisor-frontend

Component documentation

The repository contains components covered with the documentation comments using JSDoc markup language. The HTML documentation can be generated with the npm run docs script. Additionally, the documentation is automatically built with the Generate and Release Documentation GitHub action. The deployed documentation is available at https://redhatinsights.github.io/insights-inventory-frontend.

Release process

This section describes the process of getting a code change from a pull request all the way to production.

Latest image and Stage deployment

When a new pull request is opened, some jobs are run automatically, like unit tests, code style tests, E2E playwright tests, etc.

When a pull request is merged to master, a new container image is built and tagged as insights-inventory-frontend:latest. This image is then automatically deployed to the Stage environment.

1. Pre-promotion verification

Verify E2E Test Status

We use Playwright E2E tests triggered via GitHub Actions. Navigate to the Actions tab in GitHub and locate the Stage: Daily Frontend Suite workflow:

• Check latest results: If no PRs have been merged recently, you may verify the latest daily run results.
• Manual run (always recommended):
  • In Stage: Daily Frontend Suite workflow click Run workflow against the master branch.
  • Wait for completion to ensure the latest PR changes haven't introduced regressions.

2. Promoting to production

The Standard Release method uses the app-interface-bot. This is the preferred way to promote the latest validated image from the master branch.

Standard release: Automated

• Navigate to the to Bot Pipelines
• Click New pipeline (top right).
• Configure the following variables:
  • HMS_SERVICE: host-inventory
  • HOST_INVENTORY_FRONTEND: master
  • FORCE: Use --force only if GitHub CI is failing for an unrelated/known flake.
• Click Run Pipeline.
• Result: The bot will create a MR and post the link in the #insights-release Slack channel.

Fallback: Manual promotion

Use this method only if you need a targeted release (e.g., rolling back to a specific SHA or skipping a buggy commit).

• Open MR for deploy-clowder.yml file.
• Update the ref for prod-frontends and prod-multicluster-frontends namespaces

Approval and monitoring

Once the MR is open (either manually or via bot):

• Validation: Review the list of PRs included. Ensure all associated Jira cards are in "Release Pending" (no cards should be "On QA").
• Review: Request a review from another Inventory team member.
• Approval: The reviewer must comment /lgtm to trigger the automatic merge.
• Responsibility: The engineer who approved the MR is responsible for monitoring the rollout to ensure the production environment remains stable:
  • OpenShift namespace: frontends
  • Check for Pod: inventory-frontend

3. Post-release verification

After the changes have successfully landed in Production (verify the deployment is complete, not just merged):

• Trigger Prod Post-Release Sanity workflow.
• Confirm all E2E tests pass against the live production environment.

Common Problems You Might Encounter

• Some APIs we use require the latest version of their client package in order to enjoy the latest properties they provide. In case you checked the Network tab in the console and had a look at the requiered API call that should contain a property you need to fetch and use, but did not see this property in the list of properties in the Response tab, make sure you have the latest version of the client package that contains this API. To make sure the versions align, Have a look at your package.json file and compare the appropriate client package version (that should have the API you need) with the latest published version on npmjs.com. In case they don't match, update this client package to it's latest version by running this command: npm i @redhat-cloud-services/{name-of-client-package}@latest

Then, re-install the modules by running this command: rm -rf node_modules && npm install

And re-run the application. This should solve this issue.

In case these steps did not solve your issue, it is possible that the latest package had not been released yet. Please contact the appropriate team to release the package you are using, and go over the described process of updating the client package version again.