Create a Given/When/Then/But/And best practice

[javigomez]

we should write a best practice for when to use Given, when When and when Then like in here https://github.com/cucumber/cucumber/wiki/Given-When-Then but completely applied to our tests.

Something to be placed at the best practices section in the wiki https://docs.joomla.org/Testing_Joomla_Extensions_with_Codeception#Best_Practices_at_Testing

[astridx]

I have a question in this context:

Shouldn’t the Scenario
check the created user in the backend
in the file
users_frontend.feature
have a When step?

Because
And I search the user with user name "user2"
is an action and no pre-condition?

  Scenario: check the created user in the backend
    Given I am on the User Manager page
    And I search the user with user name "user2"
    Then I should see the user "user2"

And I have a suggestion for a text

Given/When/Then/But/And best practice

The scenarios within our .feature files consist of steps, also known as givens, whens, buts, thens and ands.

Technically these kind of steps are the same. When we executing the feature, each step is matched to a PHP function.

Example:

Given There is an user link,
When I see the user edit view tabs
and
Then I check available tabs "Account Details", "Assigned User Groups" and "Basic Settings"

are the steps in the Scenario:

Verify available tabs in com_users
of the feature-file /tests/codeception/acceptance/users.feature.

  Scenario: Verify available tabs in com_users
    Given There is an user link
    When I see the user edit view tabs
    Then I check available tabs "Account Details", "Assigned User Groups" and "Basic Settings"

The step
Given There is an user link
is matched to the PHP function thereIsAAddUserLink(),
the step
When I see the user edit view tabs
is matched to the PHP function iSeeTheUsereditViewTabs()
and
the step
Then I check available tabs "Account Details", "Assigned User Groups" and "Basic Settings"
is matched to the PHP function iCheckAvailableTabs($tab1, $tab2, $tab3)
of the file /tests/codeception/_support/Step/Acceptance/Administrator/User.php

    public function thereIsAAddUserLink()
    {
        $I = $this;

        $I->amOnPage(UserManagerPage::$url);
        $I->adminPage->clickToolbarButton('New');
    }


    public function iSeeTheUsereditViewTabs()
    {
        $I = $this;

        $I->adminPage->clickToolbarButton('New');
        $I->adminPage->waitForPageTitle('Users');
    }
    public function iCheckAvailableTabs($tab1, $tab2, $tab3)
    {
        $I = $this;

        $I->adminPage->verifyAvailableTabs([$tab1, $tab2, $tab3]);
    }

So, why are there these different step names?

Behaviour-driven development (BDD) means that you can turn an idea for a requirement into code simply, as long as the requirement is specific enough that everyone knows what’s going on.

We need a way to describe the requirement so that everyone – user and developer – have a common understanding of the scope of the software.

Our tests can only be successful if we have the same semantic understanding of the steps Given, When and Then!

Given

The purpose of Given is to put the system in a known state. What is the context of the system? What pre-condition must be true before the action is tested? What relevant data is in the system?

Important in this context: In most of our .feature files we use the the section Background. The background is run before each of the scenarios in our .feature file and also has impact on the state.

Examples:

Given There is a add content link
Given I search and select the user with user name "register"
Given I am on the User Manager page
Given User "User Three" did login at least once

When

The purpose of When is to describe the key action that will be performed. What will be tested? What relevant input data will be tested when the action occurs?

Examples:

This could be only one action like in the Scenario
Delete ACL

  Scenario: Delete ACL
    Given I search and select the Access Level with name "Acl Two"
    When I Delete the Access level "Acl Two"
    Then I should see "No Matching Results" for deleted user "Acl Two"

This could multiple actions in succession like in the Scenario
Check if block and activation are working

  Scenario: Check if block and activation are working
    Given I am on the User Manager page
    When I unblock the user "User Two"
    And I activate the user "User Two"
    And I login with user "user2" with password "pass2" in frontend
    Then I should see the message "Hi User Two,"

Then

The purpose of Then is to observe outcomes. The observations should be related to the business value/benefit in our feature description. In response to the action, what is the observable outcome? What are the expected results? What is the post-condition or output data observable by the user?

Examples:

Then I should see the access level "Acl Two" is created
Then Login in backend with username "User One" and password "pass1"

Please note: We should only verify outcome that is observable for the user. It is not enough to verify that all entries in the database are correct!

And, But

If we have several givens, whens or thens we could write

  Scenario: Create User without username fails
    Given There is a add user link
    When I don't fill Login Name but fulfill remaining mandatory fields: Name "User Two", Password "pass2" and Email "user2@example.com"
    When I Save the user
    Then I see the title "Users: New"
    Then I see the alert error "Invalid field:  Login Name"

But we make it read more fluently by writing

 Scenario: Create User without username fails
    Given There is a add user link
    When I don't fill Login Name but fulfill remaining mandatory fields: Name "User Two", Password "pass2" and Email "user2@example.com"
    And I Save the user
    Then I see the title "Users: New"
    But I see the alert error "Invalid field:  Login Name"

Steps beginning with And or But are exactly the same kind of steps as all the others.

Links

https://github.com/cucumber/cucumber/wiki/Given-When-Then`
https://github.com/cucumber/cucumber/wiki/Feature-Introduction
https://sites.google.com/site/unclebobconsultingllc/the-truth-about-bdd
http://docs.behat.org/en/v2.5/guides/1.gherkin.html
https://dannorth.net/whats-in-a-story/

[nibra]

Astrid, your observation regarding users_frontend.feature are correct. It should be When instead of And. Would you mind to do a PR for that?

[nibra]

Great work! Just one thing: The Gherkin statements should be valid English (UK) sentences whenever possible. So please check the grammar (I've seen some small issues; you've probably just copied them) to ensure that.

Again, very good work, please make a PR!

[astridx]

Nibra, how can I do a PR for the page
https://docs.joomla.org/Testing_Joomla_Extensions_with_Codeception#Best_Practices_at_Testing.

[nibra]

Oh, that's a wiki! Just register (if haven't done so yet) and edit!

[astridx]

Changing the Wiki is not possible for me. I get this message:

Warning: This action has been automatically identified as repetition spamming to avoid common keyword spamming. Unconstructive edits will be quickly reverted, and egregious or repeated unconstructive editing will result in your account or IP address being blocked. If you believe this edit to be constructive, please contact the documentation team and ask to be added as a jdoc contributor. A brief description of the abuse rule which your action matched is: Stupid Tricks Check

[MATsxm]

@astridx
Bonjour, could you please give me your username on the JDoc.
Thanks

[astridx]

@MATsxm Thank you. My username is astridx

[MATsxm]

Should be 👍 now

[yvesh]

Thank you @MATsxm and @astridx 👍

[astridx]

@MATsxm Thank you. Now I can edit wiki articles.

I put my text within the chapter 8 - BDD Testing using Gherkin and Codeception-
Please double check it out. Is everything OK so?

[javigomez]

cc: @pritalpatel