Improve error & debug messages for Codeception early exit

CHANGELOG.md

@@ -4,6 +4,10 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [unreleased] Unreleased
 
+### Changed
+
+- Improve `LoadSandbox` errol and messaging (used by the `WPLoader` module when `loadOnly: true`) around Codeception early exits. (thanks @andronocean)
+
 ## [4.3.4] 2024-09-13;
 
 ## Fixed

config/typos.toml

@@ -12,3 +12,4 @@ ignore-hidden = false
 [default.extend-words]
 # To handle the hipster default blog content about bike messengers gettin' caught in the rain.
 "gettin" = "gettin"
+"Automattic" = "Automattic"

includes/airplane-mode/README.md

@@ -10,7 +10,7 @@ Airplane Mode
 * [Mark Jaquith](https://github.com/markjaquith)
 
 ## About
-Control loading of external files when developing locally. WP loads certain external files (fonts, Gravatar, etc.) and makes external HTTP calls. This isn't usually an issue, unless you're working in an evironment without a web connection. This plugin removes/unhooks those actions to reduce load time and avoid errors due to missing files.
+Control loading of external files when developing locally. WP loads certain external files (fonts, Gravatar, etc.) and makes external HTTP calls. This isn't usually an issue, unless you're working in an environment without a web connection. This plugin removes/unhooks those actions to reduce load time and avoid errors due to missing files.
 
 ## Current Actions
 * removes external JS and CSS files from loading

src/WordPress/InstallationException.php

@@ -43,6 +43,7 @@ class InstallationException extends Exception
     public const SQLITE_PLUGIN_NOT_FOUND = 37;
     public const DB_DROPIN_ALREADY_EXISTS = 38;
     public const WORDPRESS_NOT_FOUND = 39;
+    public const COMMAND_DID_NOT_FINISH_PROPERLY = 40;
 
     public static function becauseWordPressFailedToLoad(string $bodyContent): self
     {
@@ -71,4 +72,14 @@ public static function becauseWordPressMultsiteIsNotInstalled(bool $isSubdomainI
 
         return new self('WordPress multisite (sub-folder) is not installed.', self::MULTISITE_SUBFOLDER_NOT_INSTALLED);
     }
+
+    public static function becauseCodeceptionCommandDidNotFinish(): self
+    {
+        return new self(
+            "The current Codeception command did not finish properly. WordPress exited early while loading. "
+            ."A plugin, theme, or WP-CLI package may have exited before the wp_loaded action could be fired. " .
+            "If there is error output above, it may provide clues.",
+            self::COMMAND_DID_NOT_FINISH_PROPERLY
+        );
+    }
 }

src/WordPress/LoadSandbox.php

@@ -123,6 +123,12 @@ class_exists(InstallationException::class);
             }
         }
 
+        if ($bodyContent === 'COMMAND DID NOT FINISH PROPERLY.') {
+            // We got here from \Codeception\Subscriber\ErrorHandler::shutdownHandler().
+            // We'll try to provide some clues to the user by adding some debug output.
+            throw InstallationException::becauseCodeceptionCommandDidNotFinish();
+        }
+
         // We do not know what happened, throw and try to be helpful.
         throw InstallationException::becauseWordPressFailedToLoad($bodyContent ?: $reason);
     }

tests/unit/lucatume/WPBrowser/WordPress/LoadSandboxTest.php

@@ -5,8 +5,10 @@
 
 use Codeception\Test\Unit;
 use Exception;
+use lucatume\WPBrowser\Tests\Traits\Fork;
 use lucatume\WPBrowser\Tests\Traits\LoopIsolation;
 use lucatume\WPBrowser\Tests\Traits\TmpFilesCleanup;
+use lucatume\WPBrowser\Traits\UopzFunctions;
 use lucatume\WPBrowser\Utils\Env;
 use lucatume\WPBrowser\Utils\Filesystem as FS;
 use lucatume\WPBrowser\Utils\Random;
@@ -24,6 +26,7 @@ class LoadSandboxTest extends Unit
 {
     use LoopIsolation;
     use TmpFilesCleanup;
+	use UopzFunctions;
 
     /**
      * It should correctly load installed WordPress
@@ -322,4 +325,68 @@ public function should_handle_wp_die_called_during_loading(): void
             $loadSandbox->load();
         });
     }
+
+    /**
+     * It should handle an unexpected early exit if something interferes with Codeception
+     *
+     * @test
+     */
+    public function should_handle_codeception_command_not_finished_error(): void {
+        $wpRootDir = FS::tmpDir('sandbox_');
+        $dbName = Random::dbName();
+        $dbHost = Env::get('WORDPRESS_DB_HOST');
+        $dbUser = Env::get('WORDPRESS_DB_USER');
+        $dbPassword = Env::get('WORDPRESS_DB_PASSWORD');
+        $db = new MysqlDatabase($dbName, $dbUser, $dbPassword, $dbHost, 'wp_');
+        $installation = Installation::scaffold($wpRootDir, '6.1.1')
+            ->configure($db)
+            ->install(
+                'http://wordpress.test',
+                'admin',
+                'admin',
+                '[email protected]',
+                'Sandbox'
+            );
+
+        $exitingPluginCode = <<<'PHP'
+<?php
+/**
+ * Plugin Name: Codeception Early Shutdown Mock
+ *
+ * Suppose a plugin or CLI package messes up and exits early, e.g. `exit(1)`, prior to `wp_loaded`.
+ * That will trigger Codeception's shutdown handler. If the suite is not finished running, and an error has not occurred,
+ * Codeception echoes a message and exits. LoadSandbox's output buffer will catch this.
+ * This plugin mocks the Codeception behavior.
+ *
+ * @see \Codeception\Subscriber\ErrorHandler::shutdownHandler()
+ */
+add_action('after_setup_theme', function () {
+    // Output and exit from \Codeception\Subscriber\ErrorHandler::shutdownHandler.
+    echo "\n\n\nCOMMAND DID NOT FINISH PROPERLY.\n";
+    exit(125);
+});
+PHP;
+
+        $muPluginsDir = $installation->getMuPluginsDir();
+        if (
+            !is_dir($muPluginsDir)
+            && !(
+                mkdir($muPluginsDir, 0755, true)
+                && is_dir($muPluginsDir)
+            )
+        ) {
+            throw new \RuntimeException('Could not create mu-plugins directory.');
+        }
+        if(!file_put_contents($muPluginsDir . '/exiting-mu-plugin.php', $exitingPluginCode)){
+            throw new \RuntimeException('Could not write exiting-mu-plugin.php.');
+        }
+
+        $this->expectException(InstallationException::class);
+        $this->expectExceptionMessage(InstallationException::becauseCodeceptionCommandDidNotFinish()->getMessage());
+
+        $this->assertInIsolation(static function () use ($wpRootDir) {
+            $loadSandbox = new LoadSandbox($wpRootDir, 'wordpress.test');
+            $loadSandbox->load();
+        });
+    }
 }