Quality Assurance/Writing feature descriptions

See Quality Assurance/Browser testing#How to contribute for a more complete list of ways to contribute; this page explains one of them.

All you need to start contributing to browser testing is a browser :) and knowledge of plain English. Yes, it's that simple.

Browser testing is all automated. We use Cucumber to check whether software features behave as expected. What Cucumber needs are descriptions of how features should behave. Makes sense, right? Here you have instructions to start contributing feature descriptions. If you need help just ask in the Discussion page.

Contributors willing to go a step further can help converting the plain English descriptions to Cucumber compatible syntax. Check the Executable specifications section below.

Ruby developers and other contributors familiar with Page Objects and Cucumber can check the documentation for running tests and writing tests.

Plain English

Acceptance Test Driven Development starts with a clear description of how a feature should behave. These plain-language specifications are the most important part of the whole project. The better the specifications of the behavior of particular features, the better the automated tests will be! For example, we might describe how Search should work in any given wiki:

On any random page in any wiki, type "main" into the search box.  
A list of results should appear, and "Main Page" should be the top result.  
On another random page in any wiki, type "ma" into the search box and click the Search icon.  
I should then be on a page with a set of search results, and "Main Page" should be one of the results."  

Executable specifications

For those interested in going deeper, there is a formal syntax for making executable specifications in Cucumber. You can find documentation and tutorials in the Cucumber website but you can cover the basics with a short introduction.

Cucumber demands specifications in a particular form, Given/When/Then:

• A Given statement should only ever mention starting conditions.
• A When statement should always be some sort of verb, or action.
• A Then statement always has the words "should" or "should not", or equivalent.

Feature: My Feature
  Scenario: Testing some aspect of My Feature
    Given <some initial condition>
    When <I take some action>
    Then <I should observe some result in the browser>

Any Given/When/Then statement may also have an arbitrary number of "And" clauses:

Scenario: Testing some complicated aspect of My Feature
  Given <some initial condition>
    And <some other condition>
  When <I take some action>
    And <I take some other action>
    And <I take yet another action>
  Then <I should observe some result in the browser>
    And <I should not observe some other result>

So the example description we gave above, for Search, becomes this automated test:

Feature: Search

  Scenario: Search suggestions
    Given I am at random page
    When I search for: main
    Then a list of suggested pages should appear
      And Main Page should be the first result

 Scenario: Fill in search term and click search
    Given I am at random page
    When I search for: ma
      And I click the Search button
    Then I should land on Search Results page