GUIDE
Dependenices
Composer
This command will download and install Composer as a system-wide command named composer, under /usr/local/bin., (*1)
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
Java
Java v1.7 is required., (*2)
INITIAL SET-UP
1. Select a location for the framework
Create a folder, ideally in a Test folder in your project, outside your Drupal webroot., (*3)
2. Create a composer JSON file Composer
Create a composer.json file in the test folder root., (*4)
{
"require": {
"cw/behat_test": "*"
},
"config": {
"bin-dir": "bin/"
},
"autoload": {
"psr-4": {
"CWTest\\": "src/"
}
}
}
From the Test folder created st step 1, run:, (*5)
composer install
4. Create the Behat folder structure
Run the bootstrap shell script:, (*6)
cd bin && ./cwtest-bootstrap.sh
cd ..
5. Update your local configuration
In your Test folder, edit Behat/behat.local.yml. Update:, (*7)
- the
base_url to your local site url
- the
drupal_root value to the path to your local drupal installation.
This is only required if you want to run tests on Chrome. Skip to step 7 if you don't., (*8)
(By default, Firefox works out-of-the-box.), (*9)
- Download chromedriver from
http://chromedriver.storage.googleapis.com/index.html?path=2.17/
- Save it to
/usr/local/bin
7. Verify Setup Successful
Navigate to the Behat folder inside your Test folder:, (*10)
cd Behat
Execute the following:, (*11)
./run-behat.sh setup firefox
Selenium will launch and run a test. You should see 1 scenarios (1 passed) in the terminal window after 15-20 seconds., (*12)
ONBOARDING TO A PROJECT
From the project Test folder, run:, (*13)
composer install
2. Create the Behat folder structure
Run the bootstrap shell script:, (*14)
cd bin && ./cwtest-bootstrap.sh
cd ..
3. Update your local configuration
In your Test folder, edit Behat/behat.local.yml. Update:, (*15)
- the
base_url to your local site url
- the
drupal_root value to the path to your local drupal installation.
This is only required if you want to run tests on Chrome. Skip to step 7 if you don't., (*16)
(By default, Firefox works out-of-the-box.), (*17)
- Download chromedriver from
http://chromedriver.storage.googleapis.com/index.html?path=2.17/
- Save it to
/usr/local/bin
5. Verify Setup Successful
Navigate to the Behat folder inside your Test folder:, (*18)
cd Behat
Execute the following:, (*19)
./run-behat.sh setup firefox
Selenium will launch and run a test. You should see 1 scenarios (1 passed) in the terminal window after 15-20 seconds., (*20)
ONGOING UPDATE
From the project Test folder, run:, (*21)
composer update
2. Update the Behat folder structure
Run the bootstrap shell script:, (*22)
cd bin && ./cwtest-bootstrap.sh
cd ..
Test Execution
Navigate to the Behat folder inside your Test folder:, (*23)
cd Behat
To execute all of the tests, select one of the following options based on the format ./run-behat.sh [tag] [profile]:, (*24)
./run-behat.sh regression firefox
or, (*25)
./run-behat.sh regression chrome
Test Results
The results of all tests will be stored in /Results/Behat/Twig_***.html, (*26)
Behat test writing process
It is a good idea to read through the LOGIN feature, page, and context files while reading through the following descriptions., (*27)
In the following, XXXX is the name of the page being tested, e.g. Basic, Article, Login, etc., (*28)
"ACTION" indicates a step that you have to do., (*29)
The basic process for writing any test would be:, (*30)
1. SCENARIOS, (*31)
Decide on a business scenario that you would like to automate., (*32)
This often comes from a User Story or piece of functionality that you'd like to test., (*33)
For the rest of the following, let's think of a login scenario where a user is going:, (*34)
- open the login page
- enter a username and password.
- click the login button.
2. FEATURE file, (*35)
This file contains the high-level test scenarios written in a Gherkin syntax., (*36)
These files are located in Behat/features/., (*37)
They all follow the naming convention XXXX.feature., (*38)
For example, in the LoginPage.feature, there are tests to ensure a valid login is successful., (*39)
ACTION: Create a .feature file, using the template provided, and write your scenario into the .feature file., (*40)
Follow the syntax used in other tests., (*41)
Where possible, re-use existing sentences from the .feature file as these will already have been automated., (*42)
If you are creating a new sentence, keep it short but descriptive., (*43)
- template -
/Sample_Files/Behat/features/LoginPage.feature
- reference - Gherkin
3. PAGE.php file, (*44)
This file contains the path, page objects, and getters/setters for all the fields on the page XXXX., (*45)
These files are located in src/Util/., (*46)
They all follow the naming convention XXXXPage.php., (*47)
For example, in the LoginPage.php, there are the username, password, and login button objects detailed., (*48)
ACTION: Create a Page.php file, and add the objects to it., (*49)
For Create/Edit/View content types, you generally want to add every object that an end-user would use to the XXXXPage.php file., (*50)
Using the template provided, create your XXXXPage.php file., (*51)
Take care to separate textfields, buttons, frames, etc, and follow the syntax and naming conventions from other PAGE files., (*52)
Where possible, always use IDs for your objects. If IDs are not available, consider using name, data-drupal-selector, or xpath., (*53)
- template -
/Sample_Files/src/Util/ArticlePage.php
4. CONTEXT.php file, (*54)
This file contains all of the functions that are specific to the XXXX page., (*55)
These files are located in src/Context., (*56)
They all follow the naming convention XXXXContext.php., (*57)
For example, in the LoginContext.php, there are functions to fill in the username and password fields, and press the login button., (*58)
ACTION: Create a XXXXContext.php file, and add the relevant functions to interact with the objects from the Page.php file., (*59)
This file will detail function for interacting with your objects., (*60)
The number of functions you write will vary from context to context - typically, the more complicated a UI is, the more functions will be required., (*61)
Follow the syntax and naming conventions from other CONTEXT files., (*62)
Keep all functions as short as possible, ideally doing one thing each, like filling in a text field., (*63)
5. behat.yml file, (*64)
This file contains most of the configuration settings that are required for behat to run., (*65)
Every new feature file that gets created will require that a new entry is made to this file., (*66)
ACTION: Follow the example of the login from lines 3-15. Copy and paste this inside the default profile, and update the login values with the correct values., (*67)
@todo: Please add section detailing the tagging process., (*68)
TROUBLESHOOTING
-
If you get API rate limit messages during the ./bootstrap.sh step, please see: API rate limit and OAuth tokens., (*69)
-
If you get the folowing when running the tests, please upgrade your version of java:, (*70)
Exception in thread "main" java.lang.UnsupportedClassVersionError: org/openqa/grid/selenium/GridLauncher : Unsupported major.minor version 51.0, (*71)
-
If you get errors related to timezone settings, add the following to your path profile (with the appropriate version of PHP):, (*72)
export PATH="/Applications/MAMP/bin/php/php5.6.7/bin:$PATH", (*73)
CREDITS
This work is sponsored and supported by Cameron & Wilding, a London Drupal Agency., (*74)
Wallogit.com
