Introduction #

Liferay Selenium Testing Principles#

Here at Liferay we recognize the need for a rapid development cycle that keeps up with the demands and needs of a rapidly transforming portal landscape. However with such a rapid development cycle we also recognize the increased possibility of regressions that can occur that may go unnoticed for long periods of time - costing a team and its clients valuable time in locating and neutralizing bugs. Following in the footsteps of companies like Google, we're endeavoring to implement an automated testing system based on the Selenium framework.

The Selenium framework that Liferay has implemented has several different components that any user or contributor should make himself familiar with. Individual test cases, which are comprised of: commands, locations, and values. Test suites, which are comprised of: individual test cases. For more information about writing individual test cases please see Liferay Selenium Conventions and Patterns.

Using the selenium scripts and suites of tests it is possible to test most common use cases and ensure functionality of the application under test (AUT). In Liferay's case this allowed us to establish a continuous integration server that will execute the suite of tests on every check in that occurs. Observe the server in action at http://hudson.liferay.com.

Articles related to Selenium:

Selenium Test Inventory

How to Run Selenium Tests

Liferay Selenium Conventions and Patterns

Selenium FAQ

What are Selenium tests?#

With the release of Liferay 4.4.0 came a slew of bundled Selenium tests. Selenium tests are a tool used for automated regressive testing. You can use Selenium to write scripts that will simulate typical use cases that test Liferay functionality. In layman's terms, Selenium clicks through windows and types in data as if it were a user. A typical use case would be to deploy whatever new feature you may have developed then running a test suite of Selenium tests to ensure that whatever fixes or features deployed are not inadvertantly breaking other areas.

How to Write Selenium Tests #

Install Selenium IDE#

Selenium IDE is an intergrated development environment for Selenium. It works as a FireFox extension that allows you to record and edit tests. For more information about Selenium IDE and the program visit http://openqa.org/selenium-ide/

Test Structure#

The Selenium Tests are located here. Inside portalweb there is the <b>portal</b> and <b>portlet</b> folder.

 ..\build\portal-web\test\com\liferay\portalweb

---

Inside the <b>portal</b> folder you can find the Portal Test Suite and general tests for Liferay Portal.

 ..\build\portal-web\test\com\liferay\portalweb\portal

The PortalWebTestSuite.java contains the test suites from all the tests. Tests are imported and organized by run order in the PortalWebtestSuite.java.

---

Inside the <b>portlet</b> folder you can find all the tests.

 ..\build\portal-web\test\com\liferay\portalweb\portlet\

When creating a new test create a folder to put the tests in and then create a test suite. In the image below the test suite is MessageBoardTests.java

No InterWiki reference defined in properties for Wiki called "image"!

Inside the test suite be sure to include all the tests within the folder and put them in order.

Selenese Converter#

Included in Liferay 4.4 is a Selenese coverter that will convert tests written in HTML into JAVA and check consistency with the code. Currently we are using the Selenium IDE to record the tests then saving them in HTML format then converting them into JAVA with the Selenese converter. To use the Selenese Coverter enter the command ant build-selenium in portal-web.

 ..\build\portal-web>ant build-selenium

How to Run Selenium Tests #

Note The following information is deprecated in the latest version of Liferay. For the most up-to-date information on running Selenium tests please see How to Run Selenium Tests.

Before running a Selenium test there are some prerequisites that must be met before beginning. Be sure to add the following line to your portal-ext.properties file:

 captcha.max.challenges=-1

Changing the captcha.max.challenges to -1 will eliminate any random text verifications that Selenium is unable to deal with.

---

If you would like to alter the default testing environment you can alter the test-portal-web.properties file located in "/build/portal-web/test/". If you do decide to alter the default testing environment you can make create a test-portal-web-ext.properties and override any of the following: browser.type=*iexplore

browser.type=*firefox

browser.type=*iehta

browser.type=*chrome

portal.url=http://localhost:8080

selenium.host=localhost

selenium.port=4444

Note: To run file upload tests, which have been added to Document Library and Image Gallery, Selenium must be run in Firefox chrome mode.

---

To run the Session Expiration test it is required that one alter the web.xml file located in bundle/appserver/webapps/root/web-inf.

Change:

<session-config> <session-timeout>30</session-timeout> </session-config>

To:

<session-config> <session-timeout>2</session-timeout> </session-config>

---

There are three components that must be running in order to run the Selenium Test Suite:

1. Tomcat
2. Selenium Server
3. Selenium RC

Start your application server. (Tomcat)

Start Selenium Server

1. In the command line navigate to the /build/lib/development directory.

2. Execute the following line - java -jar selenium-server.jar

Selenium server is now running and listening on port 4444.

Begin the test

1. In a new command line window navigate to the /build/portal-web/ directory.
2. Execute the following line:

 ant test

Please be aware that this test simulates the default omni-admin Joe Bloggs and will create at least 60 pages (one per portlet) in that private community.

This should start the test; you can monitor the commands that are being passed to the browser by observing the Selenium Server command line window, or you can directly view the commands being executed on the Firefox browser that is opened.

Troubleshooting Selenium Tests #

As you use Selenium automated scripts to test functionality you will find that they may break more frequently than initially expected. Selenium tests by their design are extremely fragile. This will help to highlight regressive errors, but it may also frustrate the tester if the reasons a certain test for breaking are not obvious. There are several ways you can go about troubleshooting the bundled tests and any tests that a user designs themselves.

Check your individual test files for errors in coding the test.#

Modify your xxxxTests.java file in .../portal-web/test/com/lifera/portalweb/portlet#

For example: If the announcements tests are giving you trouble; Try commenting out portions of the test in AnnouncementsTests.java located in

 .../portal-web/test/com/liferay/portalweb/portlet/announcements

Modify the PortalWebTestSuite.Java file to narrow the scope of your tests and if you would like to test specific functionality in the portal.#

Foreign Language and Encoding#

If your tests consist of another language with characters make sure the test is in UTF-8 encoding. The Selenese converter will convert HTML files into JAVA incorrectly if there are special characters and the HTML file is saved in ANSI.

Elements Not Found?#

Tests hanging waiting to find an element that will never come? Assertions for UI elements failing out? Frustrated with parts of the test not working? There could be any number of reasons why tests fail. Consider the following questions as you troubleshoot the issues:

1. Have you deployed the plugins that are under test? Often times users will run the full suite of tests without examining what is being tested not realizing that Hot Deployable Plugins are part of the regular test suite. Either comment them out, or deploy them to the bundle you are testing.

2. Are you running tests that require Firefox Chrome mode? If you are running the Document Library, Image Gallery, Bookmarks, or the Remote Publishing portion of the Staging tests be sure you are running the tests in Chrome mode. As of this writing, these tests test file upload capabilities or navigating to seperate servers that based on JavaScript security would not function under regular Firefox and Internet Explorer.

3. Have you properly set Session Expiration? Please read above to properly set Session Expiration.

Related Articles#

Selenium Test Inventory

How to Run Selenium Tests

Liferay Selenium Conventions and Patterns

Selenium FAQ