Skip to content

Commit

Permalink
docs: add docs on motivation and enrich main README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@BioPhoton
BioPhoton committed Sep 14, 2024
1 parent c2ef6fd commit 89540fc
Show file tree
Hide file tree
Showing 2 changed files with 233 additions and 167 deletions.
212 changes: 45 additions & 167 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,10 @@
# NxVerdaccioE2eSetup
# Buildable Test Environment Plugin

<a alt="Nx logo" href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a>
This plugin provides a way zeros configuration setup to run e2e tests in a package manager environment.

✨ **This workspace maintains enterprise grade E2E steup for vitest and verdaccio** ✨
## Getting started

This workspace maintains a scalable and maintainable E2E setup for Vite tests and Verdaccio.

## Getting started

### Register Plugin

1. Configure the plugins in `nx.json`:
1. Register and configure the plugins in `nx.json`:

```json
{
Expand All @@ -25,43 +19,61 @@ This workspace maintains a scalable and maintainable E2E setup for Vite tests an
}
```

### Configure the project you want to e2e test as published package
Now you can configure the project you want to e2e test as published package.

1. Add a `publishable` tag to the package under test
2. Add a `publishable` tag to the package under test

```jsonc
// projects/my-lib/project.json
{
"name": "my-lib",
"tags": ["publishable"]
// ...
}
```

### Configure e2e project which tests the published package
Next you need to configure the e2e project to use the package under test.

1. Add the package under test as `implicitDependency` to your e2e project
2. Configure the `setup-env` target as dependent target by using `dependsOn`
3. Add the package under test as `implicitDependency` to your e2e project.

```jsonc
// projects/my-lib-e2e/project.json
{
// ...
"e2e": {
"dependsOn": [
{
"projects": "self",
"target": "setup-env",
"params": "forward"
}
],
// ...
}
"name": "my-lib-e2e",
"implicitDependency": ["my-lib"]
}
```

### Run e2e test
4. Configure the `setup-env` target as dependent target in your e2e test project by using `dependsOn`

`nx run <e2e-project-name>:e2e`
```jsonc
{
"name": "my-lib-e2e",
"targets": {
"e2e": {
"dependsOn": [
{
"projects": "self",
"target": "setup-env",
"params": "forward"
}
]
// ...
}
}
// ...
}
```

Now you are ready to go.

5. Run your e2e test with `nx run my-lib-e2e:e2e`

## Debuggins e2e tests
Tadaaaa! 🎉

Publishable project have a `publishable` tag.
Projects that need an environment have a `npm-env` tag.
Targets that need an environment set up before running depend on `{ "projects": "self", "target": "setup-env", "params": "forward"}`.
## DX while debuggins e2e tests

Production usage:
### Production usage:

- `nx run cli-e2e:e2e` - setup environment and then run E2E tests for `cli-e2e`
@TODO figure out why we can't set the environmentRoot in the target options in `project.json`
Expand All @@ -85,140 +97,6 @@ Debug packages:
- `nx run utils:npm-publish --environmentProject cli-e2e` - publishes `utils` and `models` to the verdaccio registry configured for `cli-e2e`
- `nx run utils:npm-install --environmentProject cli-e2e` - installs `utils` and `models` from the verdaccio registry configured for `cli-e2e`
- `nx run cli-e2e:stop-verdaccio` - stops the verdaccio server for `cli-e2e`


## Motivation

### Flaws in the current setup

One of the biggest flaws of e2e setups you find in the wild is one shared environment for all projects.

This leads to a lot of problems:

- flaky tests
- long setup times
- EXTREMELY hard to debug
- hard to maintain
- IMPOSSIBLE to scale

#### Changes files during e2e

The changed files during testing, interfere with configurations on your system.

```sh
User/
└── <user-name>/
├── .npmrc # 🔓 added registry and token entry to OS user specific npm config
└──Root/ # 👈 this is your CWD
├── node_modules/
│ └── <org>
│ └── <package-name>/... # 🔓 npm install installs into repository folder
├── dist/
│ └── packages/
│ └── <project-name>/...
├── tmp/
│ └── local-registry/ # 😓 hard to debug a dynamic port
│ ├── storage/...
│ │ └── <org>
│ │ └── <package-name>/... # nx nx-release-publish saves the package's tarball here
│ └── <test-name>/...
│ └── <test-case>/...
├── package-lock.json # 🔓 npm install/uninstall installs into workspace root
└── package.json # 🔓 npm install/uninstall installs into workspace root
```

#### Task Performance

To elaborate on the performance issues, we show the different cases while writing tests.

##### Changes in source

```mermaid
flowchart TB
P[project-e2e:e2e]:::e2e-.implicit.->E[project:build]:::build;
classDef e2e stroke:#f00
classDef build stroke:#f00
```

##### Changes in the test environments

```mermaid
flowchart TB
P[project-e2e:e2e]:::e2e-.implicit.->E[project:build]:::build;
classDef e2e stroke:#f00
classDef build stroke:#f00
```

##### Changes in tests

```mermaid
flowchart TB
P[project-e2e:e2e]:::e2e-.implicit.->E[project:build]:::build;
classDef e2e stroke:#f00
```

### Solution

This workspace provides a scalable and maintainable E2E setup for Vite tests and Verdaccio.
It isolates all involved files into an isolated environment for each e2e project.

#### Changes files during e2e

The changed files during testing, are all in one isolated folder and don't interfere with your local setup.

```sh
Root/ # 👈 this is your CWD
├── dist/
│ └── packages/
│ └── <project-name>/...
└── tmp/
└── e2e/
└── <project-name>/ # e2e setup
├── storage/... # npm publish/unpublish
├── node_modules/
│ └── <org>
│ └── <package-name>/... # npm install/uninstall
├── __test__/...
│ └── <file-name>/... # e2e beforeEach
│ └── <it-block-setup>/...
├── .npmrc # local npm config configured for project specific verdaccio registry
├── package-lock.json # npm install/uninstall
└── package.json # npm install/uninstall
```

#### Task Performance

To elaborate on the performance improvements, we show the different cases while writing tests.

##### Changes in source

```mermaid
flowchart TB
P[project-e2e:e2e]:::e2e-.implicit.->S[project-e2e:setup-env]:::build;
S-.implicit.->E[project:build]:::build;
classDef e2e stroke:#f00
classDef setup-env stroke:#f00
classDef build stroke:#f00
```

##### Changes in the test environments

```mermaid
flowchart TB
P[project-e2e:e2e]:::e2e-.implicit.->S[project-e2e:setup-env]:::setup-env;
S-.implicit.->E[project:build]:::build;
classDef e2e stroke:#f00
classDef setup-env stroke:#f00
```

##### Changes in tests

```mermaid
flowchart TB
P[project-e2e:e2e]:::e2e-.implicit.->S[project-e2e:setup-env]:::build;
S-.implicit.->E[project:build]:::build;
classDef e2e stroke:#f00
```

## Connect with us!

Expand Down
Loading

0 comments on commit 89540fc

Please sign in to comment.