PLANET-5167: Introduction of features descriptions as tests

[lithrel]

Refs:

• https://jira.greenpeace.org/browse/PLANET-5167
• https://jira.greenpeace.org/browse/PLANET-5168
• https://jira.greenpeace.org/browse/PLANET-5169

Follow-up of PoC: PoC for BDD tests #77

A short reminder about Gherkin

This PR implements tests in a Gherkin format, run by Codeception.
By implementing reusable sentences and making available a documented list of those, we can try to reach a point where a tester (non-coder) writes a feature file that is playable as is, without any technical intervention. Even if this goal is not fully reached, this might greatly help with tests readability and organization for the whole team.

Tests look like this (keywords hilighted in red, parameters quoted):

Scenario: Create a new post
    Given I am on a new post page
    When I add a title "Test title"
    And I publish the post
    Then a message "Post published." is displayed

Implementation looks like this (sentences are matched by annotations @Given, @When, @Then):

    /**
     * @example I add a title "My title !"
     * 
     * @When I add a title :arg1
     */
    public function iAddATitle(string $title): void
    {
        $I = $this->tester;
        $I->fillField(EditorSelector::TITLE_FIELD(), $title);
    }

What changed since #77

• Selectors moved into constants. I'm using myclabs/phpenum for this:
  • it makes it easy to add variable parts to those strings, as everything is called like a static method
  • it gives some helpers to list all keys and values
  • it allows to type constants, making it possible to lock usage of some functions to only a specific type of constant, and fail faster and with a more obvious error message (for example, GutenbergEditor::addBlock can only take BlockSection and BlockName as params and will say so if failing, which is more explicit than failing because the selector was not found in the page)
• Method names follow more closely the sentence they describe. I'm not completely satisfied by what codeception generates, but we can also make our own name generator if we feel the need to.
• Steps (methods described with Given When and Then) were moved to Step\ namespace
• Page\ namespace is used for interactions with pages that are not steps but that can be used by steps
  • In those interactions, we can more tightly limit parameter types and make tests wrongly implemented fail faster
• 2 commands were added to facilitate development and sharing of vocabulary

Commands

p4:selectors

• lists the available selectors, ordered by class. Class name should be explicit enough. Classes currently have to be added to the command code, we should add a file scan later if needed.
• variable parts of the selectors are highlighted.

p4:steps <suite> [-i]

• lists the available steps, with examples if possible (examples are method annotations @example)
• sorted by Step files, with a short description (description taken from class comments)
• option -i displays the class::method implementing the sentence

Test

Tests passed in the CI :https://app.circleci.com/pipelines/github/greenpeace/planet4-base-fork/452/workflows/8e5b6c62-e0c4-437e-a4f5-5217fea3dac0/jobs/5075/steps.
Run it locally with tests/vendor/bin/codecept run -vv acceptance editor.feature

Review guide

• tests/__support/Command
  The two commands added, started by copying Codeception\Command\GherkinSteps
• tests/__support/Selector
  All selectors, grouped by zone as Enum
• tests/__support/Step
  All steps, grouped by topic/zone
• tests/__support/Page
  Pages interactions not declared as steps (for internal use, type hinting, etc.)
• Added commands to codeception.yml, added steps to acceptance.suite.yml

Next

• In time we should automate an export of p4:steps to make it always available and up to date for test writers.
• Add string interpolation to constants instead of just %s
• Some scenarios need context to continue (a post id just created for example), find a clean way to handle that. (It is in part why there is no public site check at the moment, I'm waiting to have a few more tests to see how to group that)
• Tests are slow, some scenarios should be grouped by chaining when-then in the same scenario
• Commands code might deserve a bit of cleanup
• Still did not solve this copy/paste problem (not a priority)

[comzeradd]

Great work 💯