diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml
index c61f9ca..6db7acb 100644
--- a/.github/workflows/e2e-tests.yml
+++ b/.github/workflows/e2e-tests.yml
@@ -13,13 +13,25 @@ jobs:
         if: ${{ !env.ACT }}
         uses: actions/checkout@v4
 
+      - name: Determine branch for E2E setup
+        id: branch
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_HEAD: ${{ github.event.pull_request.head.ref }}
+        run: |
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            echo "branch_name=$PR_HEAD" >> $GITHUB_OUTPUT
+          else
+            echo "branch_name=base" >> $GITHUB_OUTPUT
+          fi
+
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
           node-version: '20'
           cache: 'npm'
 
-      - name: Install dependencies
+      - name: Install JS dependencies
         run: npm ci
 
       - name: Setup PHP
@@ -37,11 +49,19 @@ jobs:
             composer-8.2-L12
             composer-8.2
 
+      - name: Cache Playwright browsers
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-browsers-${{ runner.os }}-v1
+          restore-keys: |
+            playwright-browsers-${{ runner.os }}-
+
       - name: Install Playwright Browsers
-        run: npx playwright install --with-deps
+        run: npx playwright install
 
       - name: Setup E2E test repo
-        run: bash tests/E2E/setup.sh
+        run: bash tests/E2E/setup.sh "${{ steps.branch.outputs.branch_name }}"
 
       - name: Run Playwright tests
         run: bash tests/E2E/launch.sh & (sleep 5 && npm run test:e2e)
diff --git a/tests/E2E/install-current-nimbus-branch.php b/tests/E2E/install-current-nimbus-branch.php
new file mode 100644
index 0000000..bb46021
--- /dev/null
+++ b/tests/E2E/install-current-nimbus-branch.php
@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+$branchName = $argv[1] ?? null;
+
+if ($branchName === null || $branchName === '') {
+    fwrite(STDERR, "Error: Branch name argument is required.\n");
+    exit(1);
+}
+
+$composerFilePath = __DIR__.'/.workdir/composer.json';
+$packageName = 'sunchayn/nimbus';
+$localPackagePath = '../../';
+
+if (! file_exists($composerFilePath)) {
+    fwrite(STDERR, "Error: composer.json not found.\n");
+    exit(1);
+}
+
+$composerJson = json_decode(
+    file_get_contents($composerFilePath),
+    true,
+    flags: JSON_THROW_ON_ERROR
+);
+
+/**
+ * Ensure repositories key exists and is an array.
+ */
+$composerJson['repositories'] ??= [];
+
+if (! is_array($composerJson['repositories'])) {
+    fwrite(STDERR, "Error: repositories must be an array.\n");
+    exit(1);
+}
+
+/**
+ * Check whether the path repository already exists.
+ */
+$pathRepositoryAlreadyDefined = false;
+
+foreach ($composerJson['repositories'] as $repository) {
+    if (
+        isset($repository['type'], $repository['url']) &&
+        $repository['type'] === 'path' &&
+        $repository['url'] === $localPackagePath
+    ) {
+        $pathRepositoryAlreadyDefined = true;
+        break;
+    }
+}
+
+/**
+ * Append the repository only if it does not already exist.
+ */
+if (! $pathRepositoryAlreadyDefined) {
+    $composerJson['repositories'][] = [
+        'type' => 'path',
+        'url' => $localPackagePath,
+        'options' => [
+            'symlink' => true,
+        ],
+    ];
+}
+
+/**
+ * Ensure require section exists.
+ */
+$composerJson['require'] ??= [];
+
+if (! array_key_exists($packageName, $composerJson['require'])) {
+    fwrite(
+        STDERR,
+        "Error: Package '{$packageName}' is not present in require.\n"
+    );
+    exit(1);
+}
+
+/**
+ * Force the package version to the requested dev branch.
+ */
+$composerJson['require'][$packageName] = "dev-{$branchName}";
+
+/**
+ * Write back composer.json with stable formatting.
+ */
+file_put_contents(
+    $composerFilePath,
+    json_encode(
+        $composerJson,
+        JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
+    ).PHP_EOL
+);
+
+echo "composer.json updated successfully.\n";
diff --git a/tests/E2E/launch.sh b/tests/E2E/launch.sh
index 75a889e..b66a89a 100644
--- a/tests/E2E/launch.sh
+++ b/tests/E2E/launch.sh
@@ -2,20 +2,65 @@
 
 set -euo pipefail
 
+print_help() {
+    cat <<EOF
+Usage: $(basename "$0") [OPTIONS]
+
+Options:
+  --workdir=PATH       Path to the work directory (default: .workdir)
+  --port1=PORT         Port for the main PHP server (default: 8000)
+  --port2=PORT         Port for the secondary PHP server (default: 8001)
+  --help               Display this help message and exit
+
+Examples:
+  $(basename "$0")
+  $(basename "$0") --workdir=custom_workdir
+  $(basename "$0") --workdir=custom_workdir --port1=9000 --port2=9001
+EOF
+    exit 0
+}
+
 # --------------------------------------
 # CONFIGURATION
 # --------------------------------------
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TARGET_DIR="$SCRIPT_DIR/.workdir"
-
-# Server ports (default values can be overridden by positional arguments)
-PORT1="${1:-8000}"
-PORT2="${2:-8001}"
-
-# Maximum time allowed for server startup
+WORKDIR_PATH=".workdir"
+PORT1=8000
+PORT2=8001
 SERVER_TIMEOUT=15
 
+# --------------------------------------
+# PARSE OPTIONS
+# --------------------------------------
+
+for arg in "$@"; do
+    case $arg in
+        --workdir=*)
+            WORKDIR_PATH="${arg#*=}"
+            shift
+            ;;
+        --port1=*)
+            PORT1="${arg#*=}"
+            shift
+            ;;
+        --port2=*)
+            PORT2="${arg#*=}"
+            shift
+            ;;
+        --help)
+            print_help
+            ;;
+        *)
+            echo "Unknown option: $arg"
+            echo "Use --help to see usage."
+            exit 1
+            ;;
+    esac
+done
+
+TARGET_DIR="$SCRIPT_DIR/$WORKDIR_PATH"
+
 # --------------------------------------
 # HELPER FUNCTIONS
 # --------------------------------------
diff --git a/tests/E2E/setup.sh b/tests/E2E/setup.sh
index b1f9cad..8f4b693 100644
--- a/tests/E2E/setup.sh
+++ b/tests/E2E/setup.sh
@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+# Note: this script is intended for the CI job.
+# Local usage:
+#   - Ensure the current branch is up to date with remote, OR
+#   - Skip running setup.sh and directly use the launch script with a local dev repository
+#     e.g. `bash tests/E2E/launch.sh --workdir=../../../nimbus-dev`
 
 set -euo pipefail
 
@@ -11,18 +16,57 @@ REPO_URL="https://github.com/sunchayn/nimbus-dev.git"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="$SCRIPT_DIR/.workdir"
 
+# --------------------------------------
+# HELPER FUNCTIONS
+# --------------------------------------
+
+print_help() {
+    cat <<EOF
+Usage: $(basename "$0") BRANCH_NAME
+
+Arguments:
+  BRANCH_NAME        Name of the Nimbus branch to set up and install. Required.
+
+Notes:
+  - Intended for CI usage. For local Playwright runs, you can skip setup.sh and run launch.sh
+    with a local dev repository:
+      bash tests/E2E/launch.sh --workdir=../../../nimbus-dev
+EOF
+    exit 0
+}
+
+# Check for help flag
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+    print_help
+fi
+
+# --------------------------------------
+# ARGUMENT PARSING
+# --------------------------------------
+
+BRANCH_NAME="${1:-}"
+
+if [[ -z "$BRANCH_NAME" ]]; then
+    echo "Error: BRANCH_NAME argument is required."
+    echo "Usage: $0 BRANCH_NAME"
+    exit 1
+fi
+
+echo "Using branch name: $BRANCH_NAME"
+
 # --------------------------------------
 # REPOSITORY SETUP
 # --------------------------------------
 
-# Reset the working directory to a clean state.
+echo "Resetting working directory at $TARGET_DIR..."
 rm -rf "$TARGET_DIR"
-mkdir "$TARGET_DIR"
+mkdir -p "$TARGET_DIR"
 
-# Clone repository into a temporary location, then move it into place.
+echo "Cloning Nimbus repository into temporary directory..."
 TEMP_DIR="$(mktemp -d)"
 git clone "$REPO_URL" "$TEMP_DIR"
 
+echo "Syncing repository to target directory..."
 rsync -a --delete "$TEMP_DIR"/ "$TARGET_DIR"/
 rm -rf "$TEMP_DIR"
 
@@ -32,37 +76,47 @@ cd "$TARGET_DIR"
 # DEPENDENCY INSTALLATION
 # --------------------------------------
 
-# Install PHP dependencies.
+# Install PHP dependencies
 if command -v composer >/dev/null 2>&1; then
-    composer install --no-progress --ansi
+    echo "Setting current Nimbus branch in composer..."
+    php "$SCRIPT_DIR/install-current-nimbus-branch.php" "$BRANCH_NAME"
+
+    echo "Installing/updating nimbus PHP package..."
+    composer update sunchayn/nimbus --no-progress --ansi
 else
     echo "Composer is not installed. Aborting."
     exit 1
 fi
 
+# Install Node dependencies
+if command -v npm >/dev/null 2>&1; then
+    echo "Installing Node.js dependencies..."
+    npm install
+else
+    echo "npm is not installed. Aborting."
+    exit 1
+fi
+
 # --------------------------------------
 # ENVIRONMENT SETUP
 # --------------------------------------
 
 ENV_FILE="$TARGET_DIR/.env"
-rm -f ENV_FILE
+echo "Setting up environment file..."
+rm -f "$ENV_FILE"
 cp "$SCRIPT_DIR/.env.template" "$ENV_FILE"
 
-# Install Node dependencies.
-if command -v npm >/dev/null 2>&1; then
-    npm install
-else
-    echo "npm is not installed. Aborting."
-    exit 1
-fi
-
 # --------------------------------------
 # APPLICATION BOOTSTRAP
 # --------------------------------------
 
-# Run migrations against a local SQLite database.
+echo "Bootstrapping application..."
+
+# Run migrations against a local SQLite database
 touch database/database.sqlite
 php artisan migrate --force
 
-# Publish Nimbus-related frontend assets.
+# Publish Nimbus-related frontend assets
 php artisan vendor:publish --tag=nimbus-assets
+
+echo "Setup complete. Ready for E2E tests or further local usage."