Improve Documentation of Project/System/Platform Requirements

[kopepasah]

Is your enhancement related to a problem? Please describe.

Yes, the documentation for installing WP Acceptance does not clearly define the project, platform and/or system requirements. This causes issue when trying to use Composer without the specific project requirements of WP Acceptance.

For example, while working on improving Composer support for the Restricted Site Access plugin, I ran into an issue when running composer install which stated that my system did not contain the necessary requirements:

➜  restricted-site-access git:(feature/composer-support) ✗ composer install
Loading composer repositories with package information
Updating dependencies (including require-dev)
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - league/uri 5.3.0 requires ext-intl * -> the requested PHP extension intl is missing from your system.
    - league/uri 4.2.3 requires ext-intl * -> the requested PHP extension intl is missing from your system.
    - league/uri 4.2.2 requires ext-intl * -> the requested PHP extension intl is missing from your system.
    - league/uri 4.2.1 requires ext-intl * -> the requested PHP extension intl is missing from your system.
    - league/uri 4.2.0 requires ext-intl * -> the requested PHP extension intl is missing from your system.
    - jane-php/open-api-runtime v4.2.0 requires jane-php/json-schema-runtime ^4.0 -> satisfiable by jane-php/json-schema-runtime[4.x-dev, v4.0.0, v4.0.1, v4.0.2, v4.0.4, v4.1.0, v4.2.0, v4.3.0, v4.4.0, v4.5.0, v4.5.1, v4.5.2, v4.5.3, v4.5.4].
    - 10up/wpacceptance dev-master requires jane-php/open-api-runtime 4.2.0 -> satisfiable by jane-php/open-api-runtime[v4.2.0].
    - jane-php/json-schema-runtime 4.x-dev requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.0.0 requires league/uri ^4.2 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3].
    - jane-php/json-schema-runtime v4.0.1 requires league/uri ^4.2 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3].
    - jane-php/json-schema-runtime v4.0.2 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.0.4 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.1.0 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.2.0 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.3.0 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.4.0 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.5.0 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.5.1 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.5.2 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.5.3 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - jane-php/json-schema-runtime v4.5.4 requires league/uri ^4.2|^5.3 -> satisfiable by league/uri[4.2.0, 4.2.1, 4.2.2, 4.2.3, 5.3.0].
    - Installation request for 10up/wpacceptance dev-master -> satisfiable by 10up/wpacceptance[dev-master].

This is expected, as these are required to run WP Acceptance. I personally use Lando for local development, so I went into the shell to run the install, but still received errors for missing system requirements. This was unexpected, as my local Lando configuration met the requirements documented on wpacceptance.readthedocs.io:

PHP 7.2+
mysqli PHP extension
Docker
Node >= 8 (WP Acceptance uses Puppeteer behind the scenes)

As such, I installed wp-local-docker-v2 in order to test installing WP Acceptance on a new WordPress install, in a blank plugin. In this scenario, I started a new site with 10updocker and configured a Single WordPress installation, with default content deleted. From there I created a blank test plugin, configured Composer with minimum-stability of dev and ran the installer command for WP Acceptance (within shell):

composer require 10up/wpacceptance:dev-master --dev

While the other requirements above were met (expected), to my surprise there was a different install error:

[www-data@4fae65ff5e05 html]$ composer require 10up/wpacceptance:dev-master --dev
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for 10up/wpacceptance dev-master -> satisfiable by 10up/wpacceptance[dev-master].
    - 10up/wpacceptance dev-master requires 10up/wpsnapshots dev-master -> satisfiable by 10up/wpsnapshots[dev-master] but these conflict with your requirements or minimum-stability.

Installation failed, deleting ./composer.json.

Here is the composer.json for that blank repo:

{
    "name": "kopepasah/wp-test-plugin",
    "authors": [
        {
            "name": "Justin Kopepasah",
            "email": "justin@kopepasah.com"
        }
    ],
    "require": {},
    "minimum-stability": "dev"
}

Describe the solution you'd like

As a developer that could find WP Acceptance useful, it would be beneficial to use this as a Composer package that clearly stated all requirements in order to use the package. As it stands now, there seem to be some required "behind the scenes" configurations that are not yet documented, including the requirement to run Composer commands within the Docker containers.

My expectation is that when the environment (local, stage, prod) is correctly configured (according to the documentation) running composer require 10up/wpacceptance:dev-master --dev would not throw any errors.

In those cases where system/platform requirements are not met, better notifications to the developer would be useful in debugging and understanding the requirements of this package.

[kopepasah]

I will note, however, that bypassing the platform requirements performs the installation as expected:

composer install --ignore-platform-reqs

[dinhtungdu]

Hi @kopepasah, what is your OS you're using locally? And how did you install PHP for that host machine?

From there I created a blank test plugin, configured Composer with minimum-stability of dev and ran the installer command for WP Acceptance (within shell)

Does the shell here mean that the shell of the docker container after you run 10updocker shell?

When you run WPAcceptance locally, you should install and run it on your HOST machine, not within another Docker environment.

[kopepasah]

Hi @kopepasah, what is your OS you're using locally? And how did you install PHP for that host machine?

MacOS, but this is not related unless running from the HOST machine is really a requirement.

Does the shell here mean that the shell of the docker container after you run 10updocker shell?

Yes.

When you run WPAcceptance locally, you should install and run it on your HOST machine, not within another Docker environment.

This does not seem correct as WP Acceptance should be able to run in containers on any CI platform, including in containers on a developers personal computer. If it is truly the case that WP Acceptance should run on the host machine then that means it requires the developer to configure the machine according to the requirements, but this is honestly just an old practice. Running in containers is reliable and predictable, unlike the variations found in a personal machine.

Is the requirement to run WP Acceptance directly on the host machine documented somewhere?

---

Lastly, my expectation here would be that I can create a bespoke WordPress plugin and run the following command to install WP Acceptance:

composer require 10up/wpacceptance:dev-master --dev

But this does not work and there is additional required configuration not documented (as this command throws errors), even when using wp-local-docker.

[dinhtungdu]

@kopepasah I tested installing wpacceptance for a fresh project inside 10updocker shell and I can install it without the problem you got. I use php-fpm 7.3.

But as I said above, you will need to run WPAcceptance from your host machine because WPAcceptance requires docker, and it's not available inside the 10up/wp-php-fpm-dev container (at least, by default).

Is the requirement to run WP Acceptance directly on the host machine documented somewhere?

Yes, see the note at the end of Project setup section. https://wpacceptance.readthedocs.io/en/latest/#project-setup.

CI is different because it has docker service available during the builds, that's why we can use WPA on CI. FYI, see: https://blog.travis-ci.com/2015-08-19-using-docker-on-travis-ci/