Merge pull request #690 from lucatume/init-doc-updates

init doc updates

.github/workflows/docs.yml

@@ -1,10 +1,5 @@
 name: docs
 on:
-  pull_request:
-    paths:
-      - 'docs/**'
-      - 'mkdocs.yml'
-      - '.github/workflows/docs.yml'
   push:
     paths:
       - 'docs/**'

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/_support/_generated/WploaderTesterActions.php

@@ -1,4 +1,4 @@
-<?php  //[STAMP] 78c0fea8c98ec2d182b5db7ffedc0a1e
+<?php  //[STAMP] 544d779e0fd8c7b70b0b5c1d37bb4034
 // phpcs:ignoreFile
 namespace _generated;
 
@@ -47,16 +47,16 @@ public function getWpRootFolder(?string $path = NULL): string {
      * The value will first look at the `WP_PLUGIN_DIR` constant, then the `pluginsFolder` configuration parameter
      * and will, finally, look in the default path from the WordPress root directory.
      *
-     * @param string $path A relative path to append to te plugins directory absolute path.
-     *
-     * @return string The absolute path to the `pluginsFolder` path or the same with a relative path appended if `$path`
-     *                is provided.
      * @example
      * ```php
      * $plugins = $this->getPluginsFolder();
      * $hello = $this->getPluginsFolder('hello.php');
      * ```
      *
+     * @param string $path A relative path to append to te plugins directory absolute path.
+     *
+     * @return string The absolute path to the `pluginsFolder` path or the same with a relative path appended if `$path`
+     *                is provided.
      * @see \lucatume\WPBrowser\Module\WPLoader::getPluginsFolder()
      */
     public function getPluginsFolder(string $path = ""): string {
@@ -69,16 +69,16 @@ public function getPluginsFolder(string $path = ""): string {
      *
      * Returns the absolute path to the themes directory.
      *
-     * @param string $path A relative path to append to te themes directory absolute path.
-     *
-     * @return string The absolute path to the `themesFolder` path or the same with a relative path appended if `$path`
-     *                is provided.
      * @example
      * ```php
      * $themes = $this->getThemesFolder();
      * $twentytwenty = $this->getThemesFolder('/twentytwenty');
      * ```
      *
+     * @param string $path A relative path to append to te themes directory absolute path.
+     *
+     * @return string The absolute path to the `themesFolder` path or the same with a relative path appended if `$path`
+     *                is provided.
      * @see \lucatume\WPBrowser\Module\WPLoader::getThemesFolder()
      */
     public function getThemesFolder(string $path = ""): string {
@@ -93,15 +93,15 @@ public function getThemesFolder(string $path = ""): string {
      * This method gives access to the same factories provided by the
      * [Core test suite](https://make.wordpress.org/core/handbook/testing/automated-testing/writing-phpunit-tests/).
      *
-     * @return FactoryStore A factory store, proxy to get hold of the Core suite object
-     *                                                     factories.
-     *
      * @example
      * ```php
      * $postId = $I->factory()->post->create();
      * $userId = $I->factory()->user->create(['role' => 'administrator']);
      * ```
      *
+     * @return FactoryStore A factory store, proxy to get hold of the Core suite object
+     *                                                     factories.
+     *
      * @link https://make.wordpress.org/core/handbook/testing/automated-testing/writing-phpunit-tests/
      * @see \lucatume\WPBrowser\Module\WPLoader::factory()
      */
@@ -115,16 +115,16 @@ public function factory(): \lucatume\WPBrowser\Module\WPLoader\FactoryStore {
      *
      * Returns the absolute path to the WordPress content directory.
      *
-     * @param string $path An optional path to append to the content directory absolute path.
-     *
-     * @return string The content directory absolute path, or a path in it.
      * @example
      * ```php
      * $content = $this->getContentFolder();
      * $themes = $this->getContentFolder('themes');
      * $twentytwenty = $this->getContentFolder('themes/twentytwenty');
      * ```
      *
+     * @param string $path An optional path to append to the content directory absolute path.
+     *
+     * @return string The content directory absolute path, or a path in it.
      * @see \lucatume\WPBrowser\Module\WPLoader::getContentFolder()
      */
     public function getContentFolder(string $path = ""): 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
 {

tests/wploadersuite/AjaxTest.php

@@ -1,9 +1,12 @@
 <?php
 
 use lucatume\WPBrowser\TestCase\WPAjaxTestCase;
+use lucatume\WPBrowser\Tests\Traits\UopzFunctions;
 
 class AjaxTest extends WPAjaxTestCase
 {
+    use UopzFunctions;
+
     public function ajaxCallback(): void
     {
         if (

tests/wploadersuite/_bootstrap.php

@@ -5,3 +5,12 @@
 if (!class_exists(WP_Post::class)) {
     throw new RuntimeException('WP_Post class not found');
 }
+
+// Work around WooCommerce enqueueing this only on admin requests.
+if (!function_exists('wc_get_page_screen_id')) {
+    function wc_get_page_screen_id(): string
+    {
+        return '';
+    }
+}
+