doc(README.md) add Requirements section, improve site failure messaging

docs/README.md

@@ -3,6 +3,26 @@
 
 The wp-browser library provides a set of [Codeception][4] modules and middleware to enable the testing of WordPress sites, plugins and themes.
 
+## Requirements
+
+Depending on the nature of your project, there are different requirements it will need to satisfy before getting started. 
+
+### Site
+
+* Ensure you're running the `vendor/bin/codecept init wpbrowser` command from the root directory of your WordPress site.
+* Ensure the directory contains the WordPress installation files. In a standard scenario you should have extracted WordPress files in this directory.
+* Ensure your installation is configured: it should contain a `wp-config.php` file.
+
+### Plugin
+
+* Ensure you're running the `vendor/bin/codecept init wpbrowser` command from the root directory of your plugin; this should be the directory that contains the PHP file defining the [plugin header][6].
+
+### Theme
+
+* Ensure you're running the `vendor/bin/codecept init wpbrowser` command from the root directory of your theme; this should be the directory that contains the `style.css` file defining [the theme header][7].
+
+If you decide to use the quick installation, then your PHP version should have the `sqlite3` extensions installed and activated. You can check this using the `php -m` command and verifying the `sqlite3` extension is among the active extensions.
+
 ## Installation
 
 Add wp-browser to your project as a development dependency using [Composer][1]
@@ -66,3 +86,7 @@ project needs and how wp-browser can help you.
 [4]: https://codeception.com/
 
 [5]: https://github.com/lucatume/wp-browser/issues/new/choose
+
+[6]: https://developer.wordpress.org/plugins/plugin-basics/header-requirements/
+
+[7]: https://developer.wordpress.org/themes/basics/main-stylesheet-style-css/ 

src/Project/SiteProject.php

@@ -38,27 +38,30 @@ public function __construct(InputInterface $input, OutputInterface $output, prot
         try {
             $this->installation = Installation::findInDir($this->workDir, false);
             $installationState = $this->installation->getState();
-
-            if ($installationState instanceof EmptyDir) {
-                throw new RuntimeException(
-                    'The WordPress installation directory is empty'
-                );
-            }
-
-            if ($installationState instanceof Scaffolded) {
-                throw new RuntimeException(
-                    'The WordPress installation directory is scaffolded, but not configured.'
-                );
-            }
-
-            $this->testEnvironment = new TestEnvironment();
         } catch (Throwable $t) {
             throw new RuntimeException(
                 'Failed to initialize the WordPress installation: ' . lcfirst($t->getMessage()),
                 0,
                 $t
             );
         }
+
+        $suggest = "Make sure you're initializing wp-browser at the root of your site project,".
+            " and that the directory contains the WordPress files and a wp-config.php file.";
+
+        if ($installationState instanceof EmptyDir) {
+            throw new RuntimeException(
+                "The WordPress installation directory is empty.\n{$suggest}"
+            );
+        }
+
+        if ($installationState instanceof Scaffolded) {
+            throw new RuntimeException(
+                "The WordPress installation directory is scaffolded, but not configured.\n{$suggest}"
+            );
+        }
+
+        $this->testEnvironment = new TestEnvironment();
     }
 
     public function getType(): string

tests/unit/lucatume/WPBrowser/Project/SiteProjectTest.php

@@ -43,11 +43,11 @@ public function should_throw_if_trying_scaffold_on_site_that_is_empty(): void
     }
 
     /**
-     * It should throw if trying to scaffol on site that is not configured
+     * It should throw if trying to scaffold on site that is not configured
      *
      * @test
      */
-    public function should_throw_if_trying_to_scaffol_on_site_that_is_not_configured(): void
+    public function should_throw_if_trying_to_scaffold_on_site_that_is_not_configured(): void
     {
         $composerFileCode = <<< EOT
 {