# Headless Billing Portal

[![written in typescript](https://img.shields.io/badge/written%20in-typescript-blue.svg)](https://www.typescriptlang.org) [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-yellow.svg)](https://github.com/prettier/prettier) [![tested with jest](https://img.shields.io/badge/tested_with-jest-99424f.svg)](https://facebook.github.io/jest/) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) [![yarn](https://img.shields.io/badge/maintained%20with-yarn-cc00ff.svg)](https://yarnpkg.com/en/) [![lerna](https://img.shields.io/badge/maintained%20with-lerna-green.svg)](https://lerna.js.org/)

## 🔧 Installation and usage

### 1. Install dependencies

```sh
pnpm install @maxio-com/self-service
npm install @maxio-com/self-service
yarn add @maxio-com/self-service
```

### 2. Import components

Import components from `@maxio-com/self-service` package as ES6 modules or include them in your HTML file.

```js
import { Components } from '@maxio-com/self-service';
```

### 3. Use components

```js
const componentsFactory = new Components({
  theme: componentsTheme,
  i18nSettings: {
    loadPath: 'loadPath-url',
    language: locale,
  },
  accessTokenUrl: 'accessTokenUrl-url',
});
```

### 4. Examples

Vue.js example is available in [vue-self-service-example](https://github.com/maxio-com/vue-self-service-example) directory.

React.js example is available in [react-self-service-example](https://github.com/maxio-com/react-self-service) directory.

## Installation

Please follow the steps described below to correctly setup mono-repository.

#### Required system dependencies

- [NodeJS](https://nodejs.org/en/) - JavaScript runtime environment.
- [pnpm](https://pnpm.io/) - package manager used to maintain project dependencies

### a. NodeJS

Install `NodeJS` JavaScript runtime based on your environemnt of choice:

For Homebrew on OS X and macOS

```sh
brew install node
```

You can also download and install NodeJS directly from the [official website](https://nodejs.org/en/).

Ensure that `NodeJS` environment is at least v14

### b. PNPM

Install `pnpm` [package manager](https://pnpm.io/installation):

### c. Checkout repository

Checkout repository from `main` branch.

### d. Install dependencies

Execute `pnpm install` command in terminal to install all required dependencies.

### e. Configure GIT hooks

Execute `npx husky install` command in terminal to setup GIT `pre-commit` and `commit-msg` hooks integration.

## mock server

For development purposes this project could use `api-adapter-mock` server. To run server make sure that required system dependencies are installed:

- [Docker Desktop](https://www.docker.com/products/docker-desktop) - Docker containers environment.

Run command defined below in the command-line interface:

| Command             | Description                               |
| ------------------- | ----------------------------------------- |
| `docker-compose up` | runs mock server instance on port `8080`. |

## ✨ npm scripts

List of useful commands that could be used by developers. Execution in the command-line interface should be prefixed with `yarn` package manager.

| Command           | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `storybook`       | run storybook for development on port `6006`         |
| `build-storybook` | build storybook production distribution.             |
| `lint`            | run linter against current application codebase.     |
| `test`            | run unit tests.                                      |
| `test:coverage`   | run unit tests with coverage reporter.               |
| `prettier`        | run code formatter process against current codebase. |
| `dpdm`            | detects circular dependencies in codebase.           |

### commit

This project uses [Conventional Commits](https://www.conventionalcommits.org) to enforce common commit standards.

| Command      | Description                        |
| ------------ | ---------------------------------- |
| `npx git-cz` | run commit command line interface. |

### build

This repository builds multiple artifacts to address different integration use cases:

| Artifact            | Description                                                                         |
| ------------------- | ----------------------------------------------------------------------------------- |
| `UMD`               | bundle with all dependencies dedicated for `browser` environment.                   |
| `EcmaScript Module` | transpiled code to EcmaScript module `exports / imports` with tree-shaking support. |
| `CommonJS Module`   | transpiled code to NodeJS `exports / imports` syntax.                               |
| `Types Definitions` | types declarations for applications implemented in `TypeScript` environment.        |

### translations

Some translations are allowed to have basic HTML tags inside like `<strong>` or `<i>`.
However, this only works for elements without additional attributes (like className), having none or a single text children and provided that we use them in places that allow by design for text formatting.

## E2E Tests

This repository uses [Playwright](https://playwright.dev/) framework for testing and automation.

### pipeline

End-to-end tests could be executed by using dedicated `GitHub Actions` workflow.
By default the `Playwright Tests` is triggered for each pull request created in the repository.

The pipeline could be also triggered manually by using `Run workflow` feature in `GitHub Actions`.

The `docker` image used in pipeline is coupled with `Playwright` version installed as NPM dependency.

### AIO tests

The **Playwright** and tests are fully integrated with AIO test management tool.
The end-to-end tests codebase could contain `tags` which refers to specific AIO test cases.

During manual pipeline execution - the `test_cycle_id` argument could be used to execute only tests cases included in
AIO Test Cycle and automatically update execution results.

### How to perform End to End Testing using Playwright locally

#### 1. Build RUC package using command:

```sh
pnpm build:browser
```

As a result `maxio-components.umd.js` will be created inside `dist` folder

#### 2. Copy assets into `e2e_pages` folder using command:

```sh
pnpm copy:e2e-assets
```

Note: You can use `pnpm clean:e2e-assets` to clean old assets first if needed

#### 3. Serve pages and assets so playwright can load it properly on specified port:

```sh
pnpm serve:e2e-assets
```

#### 4. Provide required env variables (you can refer to .env.example)

#### 5. Run playwright tests:

```sh
npx playwright test
```

#### Additional information:

- `playwright.config.ts`: Is playwright configuration file. Anything related to browser, hosts, timeouts, and parallelism can be configured there.

- `--headed` flag added to `npx playwright test` allows to open browser during tests

- `page.pause()` allows to pause the test execution and do some debugging