🪚 User testing (#243)

.changeset/happy-moons-rush.md

@@ -0,0 +1,5 @@
+---
+"create-lz-oapp": patch
+---
+
+Add --version flag

.dockerignore

@@ -7,7 +7,7 @@ docker-*.yaml
 .gitignore
 
 # CI/CD files
-.changeset
+.changeset/*.md
 .github
 .husky
 .turbo

.github/workflows/reusable-test.yaml

@@ -85,3 +85,37 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           path: ./logs
+
+  test-user:
+    name: User test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+        with:
+          submodules: "true"
+
+      - name: Setup environment
+        uses: ./.github/workflows/actions/setup-environment
+
+      - name: Test
+        run: pnpm test:user
+        # Since we're running the E2E tests in docker, we'll need to reinstall
+        # the node modules. This is a temporary solution to bridge us between
+        # non-containerized and containerized development
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # We'll collect the docker compose logs from all containers on failure
+      - name: Collect docker logs on failure
+        if: failure()
+        uses: jwalton/gh-docker-logs@v2
+        with:
+          dest: "./logs"
+
+      # We'll collect the docker compose logs from all containers on failure
+      - name: Store docker logs
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          path: ./logs

DEVELOPMENT.md

@@ -77,7 +77,7 @@ This project is built using `turborepo`. The above commands are just aliases to
 pnpm dev --filter=create-lz-oapp...
 ```
 
-### Running tests
+### Running unit & integration tests
 
 There are two options when it comes to running tests:
 
@@ -197,6 +197,60 @@ pnpm stop
 
 **Don't forget that the state of the local networks disappears after they are stopped and any deployment files created in one session will be invalid in the next one.**
 
+### Running E2E (user) tests
+
+E2E tests simulate user environment by publishing packages to a local NPM registry. They focus on ensuring that the examples we provide in this repository will work on user machines without interference of things such as:
+
+- Presence of code that is not published to NPM
+- Presence of NPM modules that are not included in package ependencies
+
+The user testing suite can be run as follows:
+
+```bash
+pnpm test:user
+```
+
+This will spin up a local NPM registry (available on [localhost:4873](http://localhost:4873) for debugging purposes), publish all packages locally and run the test suite.
+
+#### Using local NPM registry
+
+The local NPM registry can also be used to simulate arbitrary user flows without needing to link or publish packages to NPM. To do this, follow these steps:
+
+```bash
+# 1. Start the local registry and publish local packages
+pnpm registry:publish
+
+# 1B. Monitor the progress of publishing
+pnpm registry:logs
+
+# 2. Set your NPM registry to http://localhost:4873
+pnpm config set registry http://localhost:4873/
+
+# 3. Verify that the registry has been set
+pnpm config get registry
+
+# 4. Install the local packages in your project
+pnpm i
+
+# 4B. Package managers such as pnpm can cache dependencies
+#     so you might need to clear the module cache
+pnpm store prune
+```
+
+After this, your project is ready to use the local packages.
+
+Once done, the registry can be stopped by running:
+
+```bash
+pnpm registry:stop
+```
+
+Don't forget to reset the `registry` NPM configuration once done:
+
+```bash
+pnpm config set registry https://registry.npmjs.org/
+```
+
 ### Troubleshooting
 
 #### Problems with committing

docker-compose.registry.yaml

@@ -0,0 +1,84 @@
+#   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-
+#  / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \
+# `-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'
+#
+#            Docker compose for exposed test networks
+#
+#   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-
+#  / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \
+# `-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'
+version: "3.9"
+
+services:
+  # ~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~
+  #
+  #                Provides a local NPM registry
+  #
+  # .oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.
+  npm-registry:
+    image: verdaccio/verdaccio
+    ports:
+      - "4873:4873"
+    # This works in conjunction with the auth setting in uplinks section of verdaccio config
+    # 
+    # We need this to support download of any provate packages we might need
+    environment:
+      - NPM_TOKEN=${NPM_TOKEN}
+    healthcheck:
+      interval: 2s
+      retries: 10
+      test: ["CMD", "wget", "--output-document", "--tries=1", "--no-verbose", "--spider", "http://0.0.0.0:4873/-/ping"]
+    stop_grace_period: 120s
+    volumes:
+      - ./verdaccio.yaml:/verdaccio/conf/config.yaml
+
+  # ~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~
+  #
+  #        Publishes all packages to the local repository
+  #
+  # .oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.
+  publish:
+    extends:
+      file: docker-compose.templates.yaml
+      service: project
+    depends_on:
+      - npm-registry
+    # Here we build and publish all the packages locally,
+    # including any pending changesets.
+    # 
+    # Even though we enabled anonymous publishing in verdaccio,
+    # we need to specify some sort of an auth token 
+    # since we are trying to publish scoped packages. This can be anything,
+    # any non-empty string will do
+    command:
+      - /bin/bash
+      - -c
+      - |
+        pnpm config set registry http://npm-registry:4873/
+        pnpm config set //npm-registry:4873/:_authToken MOCK_TOKEN
+        pnpm build
+        pnpm release:version
+        pnpm release:publish
+
+  # ~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~
+  #
+  #                     Runs user tests
+  #
+  # .oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.
+  tests:
+    build:
+      context: .
+      target: base
+    depends_on:
+      publish:
+        condition: service_completed_successfully
+    command:
+      - /bin/bash
+      - -c
+      - |
+        pnpm config set registry http://npm-registry:4873/
+        
+        ./tests-user/create-lz-oapp.sh
+    volumes:
+      - ./tests-user:/tests-user
+

package.json

@@ -9,14 +9,19 @@
     "lint": "$npm_execpath turbo run lint",
     "logs": "docker compose logs -f",
     "prepare": "husky install",
+    "registry:logs": "docker compose -f docker-compose.registry.yaml logs -f",
+    "registry:publish": "docker compose -f docker-compose.registry.yaml run --build --rm $DOCKER_COMPOSE_ARGS publish",
+    "registry:start": "docker compose -f docker-compose.registry.yaml up npm-registry --wait $DOCKER_COMPOSE_ARGS",
+    "registry:stop": "docker compose -f docker-compose.registry.yaml down",
     "release:publish": "$npm_execpath changeset publish",
     "release:version": "$npm_execpath changeset version && $npm_execpath install --lockfile-only --prefer-offline --ignore-scripts",
     "start": "docker compose -f docker-compose.yaml -f docker-compose.local.yaml up network-britney network-vengaboys network-tango --wait $DOCKER_COMPOSE_ARGS",
     "stop": "docker compose down",
     "pretest": "$npm_execpath build",
     "test": "$npm_execpath turbo run test $DOCKER_COMPOSE_RUN_TESTS_TURBO_ARGS",
     "test:ci": "docker compose run --build --rm $DOCKER_COMPOSE_ARGS tests",
-    "test:local": ". bin/env && $npm_execpath start && $npm_execpath test"
+    "test:local": ". bin/env && $npm_execpath start && $npm_execpath test",
+    "test:user": "docker compose -f docker-compose.registry.yaml run --build --rm $DOCKER_COMPOSE_ARGS tests"
   },
   "lint-staged": {
     "**/*": [

packages/create-lz-oapp/src/index.tsx

@@ -7,9 +7,21 @@ import { Setup } from "@/components/setup";
 import { promptToContinue } from "@layerzerolabs/io-devtools";
 import { printLogo } from "@layerzerolabs/io-devtools/swag";
 
+interface Args {
+  version?: boolean;
+}
+
 new Command("create-lz-oapp")
   .description("Create LayerZero OApp with one command")
-  .action(async () => {
+  .option("-v,--version", "Output version information", false)
+  .action(async ({ version }: Args) => {
+    // If the user only asked for a version, we'll print that out and exit
+    if (version === true) {
+      const pkg = await import("../package.json");
+
+      return console.log(pkg.version);
+    }
+
     printLogo();
 
     // First we get the config from the user

packages/create-lz-oapp/tsconfig.json

@@ -5,7 +5,7 @@
     "declaration": false,
     "jsx": "react",
     "lib": ["dom", "dom.Iterable", "es2022"],
-    "resolveJsonModule": false,
+    "resolveJsonModule": true,
     "types": ["jest", "node"],
     "paths": {
       "@/*": ["./src/*"],

tests-user/create-lz-oapp.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# This is a PoC test for create-lz-oapp
+echo "Checking version of create-lz-oapp"
+npx --yes create-lz-oapp --version

verdaccio.yaml

@@ -0,0 +1,92 @@
+#   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-
+#  / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \
+# `-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'
+#
+#       Configuration of a local NPM registry for testing
+#
+#   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-.   .-.-
+#  / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \
+# `-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'   `-`-'
+
+storage: /verdaccio/storage/data
+plugins: /verdaccio/plugins
+
+# https://verdaccio.org/docs/webui
+web:
+  title: LayerZero.NPM
+  darkMode: true
+  showFooter: false
+  showSettings: false
+  showThemeSwitch: false
+  favicon: https://layerzero.network/favicon-32x32.png
+  primary_color: "#a77dff"
+  logo: https://avatars.githubusercontent.com/u/90789833?s=200&v=4
+
+# https://verdaccio.org/docs/configuration#authentication
+auth:
+  htpasswd:
+    file: /verdaccio/storage/htpasswd
+    algorithm: bcrypt
+    max_users: 1000
+
+# https://verdaccio.org/docs/configuration#uplinks
+uplinks:
+  npmjs:
+    url: https://registry.npmjs.org/
+    # We pass the NPM_TOKEN to the upstream repository in case we want to access any private packages
+    # 
+    # TODO As soon as all the packages are public, we can remove this
+    auth:
+      type: bearer
+      token_env: true
+
+# https://verdaccio.org/docs/protect-your-dependencies/
+# https://verdaccio.org/docs/configuration#packages
+packages:
+  # 
+  # We will not proxy the packages from this repo
+  # 
+  # Since we want to proxy some of the NPM packages,
+  # we cannot just use a pattern like "@layerzerolabs/*"
+  # 
+
+  # We will not proxy any *devtools* packages
+  "@layerzerolabs/**devtools**": &local-package-rules
+    access: $all
+
+    # allow all known users to publish/publish packages
+    # 
+    # this does not mean that anyone can publish to NPM
+    # (in fact verdaccio will not publish to NPM ever),
+    # this just means we don't need to be authenticated to the local registry 
+    # in order to publish packages
+    publish: $all
+    unpublish: $all
+
+  # We will not proxy any toolbox* packages
+  "@layerzerolabs/toolbox-**": *local-package-rules
+
+  # And we will not proxy create-lz-oapp
+  "create-lz-oapp": *local-package-rules
+
+  # The rest of the packages we'll proxy to the public NPM repo
+  "**": 
+    <<: *local-package-rules
+
+    # if package is not available locally, proxy requests to 'npmjs' registry
+    proxy: npmjs
+
+# https://verdaccio.org/docs/configuration#server
+server:
+  keepAliveTimeout: 60
+
+# https://verdaccio.org/docs/configuration#offline-publish
+publish:
+  allow_offline: true
+
+middlewares:
+  audit:
+    enabled: true
+
+# https://verdaccio.org/docs/logger
+log: { type: stdout, format: pretty, level: http }