docs: polish main readme add images

README.md

@@ -1,4 +1,4 @@
-# Buildable Test Environment Plugin
+# Nx Verdaccio Environment Plugin
 
 This plugin provides a zeros configuration setup to run e2e tests in a package manager environment.
 
@@ -72,67 +72,87 @@ Now you are ready to go.
 
 Tadaaaa! 🎉
 
-## DX while debugging e2e tests
+**Example usage:**
+- `nx run cli-e2e:e2e` - setup environment and then run E2E tests for `cli-e2e`
+- `nx run cli-static-e2e:e2e --environmentRoot static-environments/user-lists` - setup NPM in existing environment and then run E2E tests for `cli-static-e2e`
 
-### 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`
-- `nx run cli-static-e2e:e2e --environmentRoot static-environments/user-lists` - setup NPM stuff in existing environment and then run E2E tests for `cli-static-e2e`
+## DX while debugging e2e tests
 
 Debug full environment in 1 setup:
 
 - `nx run cli-e2e:setup-env` - setup environment for `cli-e2e`
-  - `nx run cli-e2e:setup-env --keepServerRunning` - keeps verdaccio running after setup
-- `nx run cli-e2e:stop-verdaccio` - stops the verdaccio server for `cli-e2e`
+  - `nx run cli-e2e:setup-env --keepServerRunning` - keeps Verdaccio running after setup
+- `nx run cli-e2e:stop-verdaccio` - stops the Verdaccio server for `cli-e2e`
 
 Debug full environment in 2 steps:
 
-- `nx run cli-e2e:bootstrap-env` - setup folders and starts verdaccio for `cli-e2e`
+- `nx run cli-e2e:bootstrap-env` - setup folders and starts Verdaccio for `cli-e2e`
 - `nx run cli-e2e:install-env` - bootstraps and installs all dependencies for `cli-e2e`
-- `nx run cli-e2e:stop-verdaccio` - stops the verdaccio server for `cli-e2e`
+- `nx run cli-e2e:stop-verdaccio` - stops the Verdaccio server for `cli-e2e`
 
 Debug packages:
 
-- `nx run cli-e2e:bootstrap-env` - setup folders and starts verdaccio for `cli-e2e`
-- `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`
-
+- `nx run cli-e2e:bootstrap-env` - setup folders and starts Verdaccio for `cli-e2e`
+- `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`
 
+## Benefits in depth
 
-## Solution
+In the below we point out a **scalable** and **maintainable** setup for Verdaccio environments.
 
-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.
+### 🛡️ Isolation of Files During E2E Tests
 
-### Changes files during e2e
+All files that change during testing are contained within an isolated folder, ensuring they don't interfere with your local setup or other tests.
 
-The changed files during testing, are all in one isolated folder and don't interfere with your local setup.
+By isolating the environment for each E2E project, you avoid conflicts with the local file system and package manager configurations, enabling parallel test execution without issues like publish, install or file conflicts.
 
 ```sh
-Root/ # 👈 this is your CWD
+Root/
 ├── 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
+├── tmp/
+│    └── e2e/
+│        └── <project-name>/
+│            ├── storage/... # npm publish/unpublish
+│            │   └── @my-org
+│            │       └── my-lib/...
+│            ├── node_modules/
+│            │   └── <org>
+│            │        └── <package-name>/... # npm install/uninstall 
+│            ├── __test__/...
+│            │   └── <test-file-name>/... 
+│            │        └── <it-block-setup>/...
+│            │             └── test.file.ts
+│            ├── .npmrc # local npm config configured for project specific Verdaccio registry
+│            ├── package-lock.json # skipped creation by default
+│            └── package.json # npm install/uninstall
+└── packages/
+    └── <project-name>/...
 ```
 
-### Task Performance
+### 🚀 Scalability - A Parallel-Friendly Setup
+
+This solution allows for **parallel execution** of tests, which was not possible before due to conflicts with file systems and package managers.
+
+- ⏱️No more waiting for tests to run sequentially. With isolated environments, each E2E test can run independently without interfering with others.
+- ⏱️Environment setup and test setup are separated, which means **significantly faster execution** of the tests and less overhead in CPU and general runtime. 
+
+### ⚡ Task Performance - Optimized Execution
+
+To further improve task performance, we can now treat the E2E environment as **build output**. 
+No need for a running server anymore.
+
+This allows us to **cache** the environment and **reuse** it across tests, leading to faster performance:
 
-To elaborate on the performance improvements, we show the different cases while writing tests.
+- 🔥 As it is decoupled from the running server we can now save cache the target
+- 🔥 No need to stop and restart the server between tests, saving CPU and memory
+- 🔥 No need to uninstall packages or delete storage folders manually. We can simply delete the isolated folder when needed.
+- 🔥 The system only installs the necessary packages, further reducing time and resource usage.
+
+![utils-project-graph-idle.png](docs%2Futils-project-graph-idle.png)
 
 #### Changes in source
 
@@ -164,6 +184,29 @@ S-.implicit.->E[project:build]:::build;
 classDef e2e stroke:#f00
 ```
 
+### ✨ DX - Developer Experience Simplified
+
+The **NX task graph** makes it easier to discover and understand the setup. Instead of relying on complex global setup scripts:
+
+- 🤌 No need for global setup files teardown or setup at all. The only connection to the tests files is just another target that runs before the E2E tests.
+- 🤌 The process is faster because the test environment doesn’t require ongoing CPU or memory once set up.
+- 🤌 Errors are easier to debug. Every step is on its own debugable.
+
+### 🔧 Maintainability - Easy to Update and Manage
+
+This approach makes the E2E setup more **maintainable** and easier to serve edge cases:
+
+- A fine-grained task graph makes it easy to understand the project
+- Since the environment doesn’t require a constantly running server, maintaining the setup becomes much simpler. The environment can be cached as a build output, reducing complexity.
+- as the cleanup logic of a test is just deleting the files this debug effort is gone completely 
+- The NX task graph provides a clear visual overview of the process, making it easy to see what runs when and how the environment is set up.
+- Configuring a test setup is in a single place and provides fine-grained configuration
+
+![utils-task-graph-idle.png](docs%2Futils-task-graph-idle.png)
+
+In summary, this new setup offers a more scalable, maintainable, and performant way to handle E2E testing. 
+By isolating environments and using NX’s powerful tools, it becomes easier to run, manage, and debug E2E tests across projects.
+
 ## Connect with us!
 
 - [Check out our services](https://push-based.io)

docs/motivation.md

@@ -46,18 +46,18 @@ export async function setup() {
   // `npm config set //localhost:${verdaccioPort}:_authToken "my-auth-token"`
   configureRegistry(verdaccioPort);
 
-  // Publish the package to test to the Verdacio storage (local-registry/storage)
-  // `npm publish @my-org/[email protected] --registry=http://localhost:${verdaccioPort}`
+  // Publish all packages to the Verdacio storage (local-registry/storage)
+  // `npm publish <package-name> --registry=http://localhost:${verdaccioPort}`
   await publishProject('my-lib');
 
-  // Install the package locally
-  // `npm install my-lib --registry=http://localhost:${verdaccioPort}`
+  // Install all packages locally
+  // `npm install <package-name> --registry=http://localhost:${verdaccioPort}`
   await installProject('my-lib');
 }
 
 export async function teardown() {
-  // Uninstall the package from the Verdacio storage (local-registry/storage)
-  // `npm uninstall my-lib`
+  // Uninstall all package from the Verdacio storage (local-registry/storage)
+  // `npm uninstall <package-name>`
   await uninstallProject('my-lib');
 
   // Revert configure npm with form the created Verdaccio registry
@@ -99,10 +99,14 @@ User/
         │   └── my-lib-e2e/
         │       └── some.test.ts
         ├── tmp/
-        │   └── local-registry/
-        │       └── storage/
-        │           └── @my-org
-        │               └── my-lib/... # npm publish saves the package's tarball here
+        │    ├── e2e/...
+        │    │   └── <test-file-name>/... 
+        │    │        └── <it-block-setup>/...
+        │    │             └── test.file.ts
+        │    └── local-registry/
+        │        └── storage/
+        │            └── @my-org
+        │                └── my-lib/... # npm publish saves the package's tarball here
         ├── package-lock.json # 🔓 npm install/uninstall installs into workspace root
         └── package.json # 🔓 npm install/uninstall installs into workspace root
 ```
@@ -140,7 +144,9 @@ To run 1 E2E test the following chain has to happen:
 
 As you can see, the majority of the tasks are just here as we can't parallelize. :(
 
-### 🐢 Task Performance
+### 🐢 Task Graph & Performance
+
+Due to above reasons the project graph is hard to optimize and opaque as everything is hidden in 2 nodes  
 
 We already scratched that topic a bit, but in this chapter we can go in full detail.
 Let's start with looking at the steps from above.