Fix up doc blocks as example for Webdriver page classes and tests.

Author: dextercowley

tests/CHANGELOG

@@ -26,6 +26,9 @@ $ -> Language fix or change
 - -> Removed
 ! -> Note
 
+2-May-2013 Mark Dexter
+ # Fix up doc blocks as example for Webdriver page classes and tests.
+
 30-Apr-2013 Mark Dexter
  # Fix system tests for clearfix class in front end
 

tests/system/webdriver/Pages/Menus/MenuItemsManagerPage.php

@@ -8,14 +8,44 @@
 use SeleniumClient\WebElement;
 
 /**
- * Class for the back-end control panel screen.
+ * @package     Joomla.Test
+ * @subpackage  Webdriver
  *
+ * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
+ * @license     GNU General Public License version 2 or later; see LICENSE
+ */
+
+/**
+ * Page class for the back-end menu items manager screen.
+ *
+ * @package     Joomla.Test
+ * @subpackage  Webdriver
+ * @since       3.0
  */
 class MenuItemsManagerPage extends AdminManagerPage
 {
+	/**
+	 * XPath string used to uniquely identify this page
+	 *
+	 * @var    string
+	 * @since  3.0
+	 */
 	protected $waitForXpath =  "//ul/li/a[@href='index.php?option=com_menus&view=items']";
+
+	/**
+	 * URL used to uniquely identify this page
+	 *
+	 * @var    string
+	 * @since  3.0
+	 */
 	protected $url = 'administrator/index.php?option=com_menus&view=items';
 
+	/**
+	 * Array of filter id values for this page
+	 *
+	 * @var    array
+	 * @since  3.0
+	 */
 	public $filters = array(
 			'Menu' => 'menutype',
 			'Max Levels' => 'filter_level',
@@ -24,6 +54,12 @@ class MenuItemsManagerPage extends AdminManagerPage
 			'Language' => 'filter_language',
 			);
 
+	/**
+	 * Array of toolbar id values for this page
+	 *
+	 * @var    array
+	 * @since  3.0
+	 */
 	public $toolbar = array (
 			'New' => 'toolbar-new',
 			'Edit' => 'toolbar-edit',
@@ -38,23 +74,29 @@ class MenuItemsManagerPage extends AdminManagerPage
 			'Help' => 'toolbar-help',
 	);
 
+	/**
+	 * Array of submenu links used for this page
+	 *
+	 * @var    array
+	 * @since  3.0
+	 */
 	public $submenu = array (
 			'option=com_menus&view=menus',
 	);
 
 	/**
 	 * Add a new menu item in the Menu Manager: Menu Items screen.
 	 *
-	 * @param string   $menuItemType   One of the allowed Menu Item Types (Single Article, Featured Contacts, etc.)
 	 * @param string   $title          Menu Title field
+	 * @param string   $menuItemType   One of the allowed Menu Item Types (Single Article, Featured Contacts, etc.)
 	 * @param string   $menuLocation   Menu Location field
 	 * @param array    $otherFields    associative array of other fields in the form label => value.
 	 *
 	 * Note that there a special field types for the request variable (e.g., article name or category name) which is required by some menu types.
 	 * This can be designated in the $otherFields with any of the following labels: 'request', 'category', 'article', 'contact', 'newsfeed', 'weblink'.
 	 * For example: array('article' => 'Australian Parks').
 	 *
-	 * @return  MenuItmesManagerPage
+	 * @return  MenuItemsManagerPage
 	 */
 	public function addMenuItem($title='Test Menu Item', $menuItemType='List All Categories', $menuLocation = 'Main Menu', array $otherFields = array())
 	{
@@ -75,7 +117,14 @@ public function addMenuItem($title='Test Menu Item', $menuItemType='List All Cat
 		return $this->test->getPageObject('MenuItemsManagerPage');
 	}
 
-
+	/**
+	 * Edit a menu item in the Menu Manager: Menu Items screen.
+	 *
+	 * @param string   $title          Menu Title field
+	 * @param array    $fields         associative array of fields in the form label => value.
+	 *
+	 * @return  void
+	 */
 	public function editMenuItem($title, $fields)
 	{
 		$this->clickItem($title);

tests/system/webdriver/tests/menus/MenuItemsManager0001Test.php

@@ -1,5 +1,11 @@
 <?php
-
+/**
+ * @package     Joomla.Test
+ * @subpackage  Webdriver
+ *
+ * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
+ * @license     GNU General Public License version 2 or later; see LICENSE
+ */
 require_once 'JoomlaWebdriverTestCase.php';
 
 use SeleniumClient\By;
@@ -9,25 +15,39 @@
 use SeleniumClient\DesiredCapabilities;
 
 /**
- * This class tests the  Manager: Add / Edit  Screen
- * @author Mark
+ * This class tests the  Manager: Add / Edit  Screen.
  *
+ * @package     Joomla.Test
+ * @subpackage  Webdriver
+ * @since       3.0
  */
 class MenuItemsManager0001Test extends JoomlaWebdriverTestCase
 {
 	/**
+	 * The page class being tested.
 	 *
-	 * @var MenuItemsManagerPage
+	 * @var     MenuItemsManagerPage
+	 * @since   3.0
 	 */
 	protected $menuItemsManagerPage = null; // Global configuration page
 
+	/**
+	 * Login to back end and navigate to menu item manager.
+	 *
+	 * @since   3.0
+	 */
 	public function setUp()
 	{
 		parent::setUp();
 		$cpPage = $this->doAdminLogin();
 		$this->menuItemsManagerPage = $cpPage->clickMenu('Main Menu', 'MenuItemsManagerPage');
 	}
 
+	/**
+	 * Logout and close test.
+	 *
+	 * @since   3.0
+	 */
 	public function tearDown()
 	{
 		$this->doAdminLogout();
@@ -40,10 +60,9 @@ public function tearDown()
 	public function constructor_OpenEditScreen_MenuEditOpened()
 	{
 		$this->menuItemsManagerPage->clickButton('toolbar-new');
-
-		/* @var $menuItemEditPage MenuItemEditPage */
 		$menuItemEditPage = $this->getPageObject('MenuItemEditPage');
 		$tabIds = $menuItemEditPage->getTabIds();
+		// Keep the following line commented to make it easy to generate values for arrays as fields change.
 // 		$menuItemEditPage->printFieldArray($menuItemEditPage->getAllInputFields($tabIds));
 		$menuItemEditPage->clickButton('toolbar-cancel');
 		$this->menuItemsManagerPage = $this->getPageObject('MenuItemsManagerPage');
@@ -77,6 +96,7 @@ public function getMenuItemTypes_ShouldMatchExpected()
 		$this->menuItemsManagerPage->clickButton('toolbar-new');
 		$menuItemEditPage = $this->getPageObject('MenuItemEditPage');
 		$actualMenuItemTypes = $menuItemEditPage->getMenuItemTypes();
+		// Keep the following lines commented. They make it easy to re-generate the array of menu types as more are added.
 // 		foreach ($actualMenuItemTypes as $array)
 // 		{
 // 			echo "array('group' => '" . $array['group'] . "', 'type' => '" . $array['type'] . "' ),\n";