Joomla! Documentation - User contributions [en]

Joomla info page/es-ES

2016-08-26T07:47:31Z

Javiparati: /* ¿Cómo puedes apoyar a Joomla!? */ Updated links

= Spanish =

== ¿Qué es Joomla? ==
Joomla es un premiado sistema de Gestión de Contenidos (CMS), que permite crear sitios Web y poderosas aplicaciones online. Muchos aspectos, incluyendo su fácil uso y extensibilidad han convertido a Joomla! en el software para Web más popular. Y lo mejor de todo, Joomla es Software Libre disponible gratuitamente para todo el mundo. Entre los beneficios de Joomla se incluye:

* Fácil instalación
* Simple mantenimiento del web
* Seguridad y estabilidad
* Potentes extensiones comerciales y gratuitas
* Una enorme cantidad de plantillas para cambiar fácilmente el look de tu web.

Tienes más información sobre Joomla! en español [http://docs.joomla.org/Joomla_brochure/es-ES en este otro artículo de la documentación].

== ¿Dónde conseguir Joomla? ==
* Descarga Joomla! desde los [http://www.joomla.org/download.html repositorios oficiales].
* Descarga los paquetes de idioma español de los [http://community.joomla.org/translations.html grupos de traducción acreditados] desde aquí:
** [http://joomlacode.org/gf/project/jtranslation/frs/?action=FrsReleaseBrowse&frs_package_id=30 Paquetes de la rama 1.5.x]
** [http://joomlacode.org/gf/project/jtranslation1_6/frs/?action=FrsReleaseBrowse&frs_package_id=5597 Paquetes de la rama 2.5.x]
** [http://joomlacode.org/gf/project/jtranslation3_x/frs/?action=FrsReleaseBrowse&frs_package_id=6445 Paquetes de la rama 3.0.x]
* Otras traducciones
** [http://joomlacode.org/gf/project/spanishlanguage/frs/ Traducciones más antiguas del grupo acreditado anterior (incluye traducciones de la rama 1.0.x)]

== ¿Dónde descargar extensiones? ==
* Descarga extensiones en: http://extensions.joomla.org/

== ¿Dónde conseguir documentación para Joomla? ==
* Documentación en inglés: http://docs.joomla.org/

== ¿Dónde conseguir soporte/ayuda para Joomla? ==
* Soporte gratuito en Inglés: http://forum.joomla.org/
* Soporte gratuito en Español:
** http://forum.joomla.org/viewforum.php?f=24
** http://magazine.joomla.org/international-stories-all/articles-in-spanish-all
* Soporte gratuito en lugares no oficiales:
** http://foro.comunidadjoomla.org
* Soporte comercial: http://resources.joomla.org/ (website en Inglés)

== Eventos regionales / Joomladays ==
Las comunidades locales organizan eventos Joomla! conocidos como ''Joomla!Days'' por todo el mundo. Un Joomla Day es un evento creado exclusivamente para los usuarios de Joomla! y sus proyectos relacionados. Habitualmente tienen una audiencia regional. Más información en: http://events.joomla.org/joomla-days.html

== Joomla User Groups (JUG) ==
Los Grupos de usuarios de Joomla (JUG) son una manera magnífica de conocer gente, conseguir ayuda para un proyecto, o compartir las experiencias con otros usuarios de Joomla. Joomla! está en todos los lugares del mundo así que revisa si ya existe algún JUG en tu zona. En caso contrario, ¿Por qué no creas uno?

* JUGs en Centro América: http://community.joomla.org/user-groups/central-america.html
* JUGs en el Caribe: http://community.joomla.org/user-groups/caribbean.html
* JUGs en Sud América: http://community.joomla.org/user-groups/south-america.html
* JUGs España: http://community.joomla.org/user-groups/europe/spain.html

* Preguntas frecuentes JUG: http://community.joomla.org/jug-faq-spanish.html

== ¿Cómo puedes apoyar a Joomla!? ==
* Responde dudas de otras personas en los foros http://forum.joomla.org/viewforum.php?f=24&sid=cf489f4ab48512121a5de9da481fba9f
* Escribe o traduce un tutorial o documentación https://docs.joomla.org/JDOC:How_to_Contribute_to_Joomla!_Documentation/es
* Desarrolla una Extensión o una plantilla de diseño https://docs.joomla.org/Portal:Developers/es
* Testea y comunica los errores que encuentres https://docs.joomla.org/Filing_bugs_and_issues/es
* Únete a un equipo de trabajo Joomla! https://volunteers.joomla.org/working-groups
* Colabora en la organización y participa en los eventos Joomla! https://events.joomla.org/
* Apoya económicamente o de otras maneras: http://contribute.joomla.org/

Code sprints

2016-05-25T07:16:33Z

Javiparati:

<noinclude><languages /></noinclude>

<translate>

A code sprint is a dedicated session in which a group of volunteers come together at a geographic location to work on code for the Joomla project. Examples of code sprint sessions could include UI/UX improvements, working on new features, or long term planning and architecture work. Typically, six to ten experienced individuals will be brought together for two days for these events. If you wish to form your own sprint then read the [[S:MyLanguage/Joomla:Sprint_Policy|policy]]
</translate>

<translate>

The code sprints are organised by the Joomla community together with the Production Leadership Team. These events are supported by the OpenSourceMatters and other sponsors.
</translate>

<translate>

Code Sprints in 2013:
* '''Rapid Application Development Code Sprint''', July 2013, Pistoia, Italy
* '''Code stability and bug triage Code Sprint''', Aug 2013, Nashville, Tennessee, USA. More info:
</translate> http://community.joomla.org/blogs/leadership/1757-call-for-participants-for-code-sprint.html

<translate>

Code Sprints in 2014:
* '''Architecture Sprint''', Feb 8-9, San Jose, California, USA.
* '''JUX Sprint''', July 8-9, More info: http://developer.joomla.org/cms/user-experience/610-jux-code-sprint-report.html
* '''Bug Clean Up Sprint''', July 26-27, More info: http://magazine.joomla.org/issues/issue-aug-2014/item/2228-joomla-bug-sprint-in-manchester
* '''Code Style Code Sprint''', Oct 11-12, Madrid, Spain. More info at: http://magazine.joomla.org/issues/issue-nov-2014/item/2353-two-joomla-code-sprints
* '''Code Testing Code Sprint''', Oct 14, Montabaur, Germany. More info at: http://thephp.cc/viewpoints/blog/2014/10/joomla-phpunit-code-sprint
</translate>

<translate>
Code Sprints in 2015:</translate>
<translate>
* '''Joomla 4 Architecture Sprint''', July 10-12, Odense, Denmark. More info at: http://volunteers.joomla.org/reports/115-joomla-4-architecture-sprint-odense-dk</translate>
<translate>
* '''Joomla 4 UX and Architecture Sprint''', October 10-12, Athens, Greece.</translate>
<translate>
* '''Joomla! Automated Testing Code Sprint''', October 28th - November 2nd, Karlsruhe, Germany. More info at: https://magazine.joomla.org/issues/issue-december-2015/item/2912-the-joomla-automated-testing-code-sprint-2015</translate>
<translate>

[[Category:Events]]
</translate>

GSOC 2016 Project Ideas

2016-03-02T12:39:44Z

Javiparati: /* Project VIII: Browser Automated Tests for Joomla! CMS (covering Users and Content features) */

== Welcome to GSoC 2016 Ideas Page ==
Welcome to the [[GSOC_2016|Joomla! Google Summer of Code (GSoC) 2016 project]] ideas page. As we move forward with the 2016 version of the Joomla! GSoC, we will post ideas that have been submitted to the GSoC Team below.

Please keep in mind that projects need to be realistically something that is able to be functionally completed by a student working full time for about eight weeks. Thanks!

If you are interested in participating as a student please review the materials on applying that are available at [http://www.google-melange.com/gsoc/document/show/gsoc_program/google/gsoc2015/help_page Google]. We strongly encourage you to ask questions about process and ideas on our [https://groups.google.com/forum/#!forum/jgsoc-2016 joomla-gsoc mailing list].

Guidelines for sending proposal are present on our [https://docs.joomla.org/GSOC_2016 GSoC Home Page]

Find examples of other years at https://docs.joomla.org/GSOC_2014_Project_Ideas



[[Image:Gsoc2016.png|250px|center|link=GSOC 2016]]
== Idea Pool ==

=== Joomla CMS Ideas ===

====Project I: Improved multi-lingual content management ====
<table border="0" style="width:100%">
<tr>
<th>'''Project Description:'''</th>
</tr>
<tr>
<td>The idea is that when users want to translate content items on a multi-language site, they can have the articles side-by-side (dual-pane). This way you don't have to switch back and forth between articles. Respect also the ACL settings. So someone assigned for Dutch cannot translate any French documents for example.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>A dual-pane translation screen<br>An ACL setting for allowing access to language based articles</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>PHP, Joomla CMS multi-lingual system, JavaScript, Joomla ACL</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium to Hard</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:rob@pollen-8.co.uk Rob Clayburn],[mailto:jean-marie.simonet@community.joomla.org Jean-Marie Simonet]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project II: Shareable Draft Content ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>There is currently no easy way to share a draft version of an unpublished article with people who do not have Administrator access. This project would add elements to the Articles: Edit user interface that would support the generation of a shareable link that would allow those with the link to view a draft version of an article. This project would be a complete new feature that could be merged into Joomla 3.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>The details of the user interface would be subject to change/discussion, but could look something like the following:
A new "Save as Draft" toolbar button on the Articles: Edit page. When clicked the article will be saved as a draft in the content version history. The version history page will need to be modified to show this special version of the article.
A new "Share" toolbar button on the same page. When clicked, the draft version of the article opens in a new tab with a special URL which can be copy-pasted so that the draft may be shared prior to publication.
Bonus points for adding a "Preview" toolbar button that will open a new browser tab with a preview of the article currently being edited, without needing to save the article first.
Code must be accompanied by documentation in the form of wiki pages and full help screens. Code must be accompanied by appropriate tests.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>PHP, Joomla CMS</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:theachalaggarwal@gmail.com Achal Aggarwal], [mailto:coolbung@gmail.com Ashwin Date]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project III: Administrator Menu Editor ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>This has been discussed at some length here: https://issues.joomla.org/tracker/joomla-cms/5492</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>An appropriately coded extension that could be merged into Joomla 3.x.
Code must be accompanied by documentation in the form of wiki pages and full help screens.
Code must be accompanied by appropriate tests.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>PHP, Joomla CMS</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:peter.martin@community.joomla.org Peter Martin], [mailto:tharuna.b@gmail.com Tharuna Balaji]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project IV: Embedded Content Done Right! ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Develop a unified framework for adding any form of embedded content. A standardised syntax for embedded content tags would be used to call a content plugin that would parse the tag and call plugins in a new embed group to return the appropriate embed code.

This builds on the idea of oembed(http://oembed.com/) but with the capability of overcoming the problems of invalid content associated with some oembed providers. It is not restricted to oembed providers and can be used to embed any kind of content for which an embed plugin can be written. Support for new data sources can be added by writing an embed plugin, making it easy for site builders to integrate new embed sources to their sites. We would gain a powerful, extendable method of embedding content anywhere that supports content plugins.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>An appropriately coded set of plugins that could be merged into Joomla 3.x, including a selection of embed extensions for popular services such as YouTube, Vimeo, Slideshare, Twitter, Facebook, MediaWiki, etc.

Bonus points for writing a JavaScript extension for TinyMCE to make it even easier to embed content.

Code must be accompanied by documentation in the form of wiki pages and full help screens.

Code must be accompanied by appropriate tests.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>PHP, Joomla CMS</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Possible mentors:'''</th>
</tr>
<tr>
<td>NA</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project V: NoSQL Database Driver (Redis, MongoDB) ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>The goal of this is project is to add a lightweight database driver for the most commonly used NoSQL databases (Redis, MongoDB) to the Joomla CMS,
and not to write yet another ORM, that is outside the scope of this project dued to the 8 weeks timeframe.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Important Links:'''</th>
</tr>
<tr><td>The original pull request: “implementation of Redis caching” https://github.com/joomla/joomla-cms/pull/3615 merged on Joomla 3.4</td></tr>
<tr><td>An open pull request “Redis sessions handler” https://github.com/joomla/joomla-cms/pull/7659</td></tr>
<tr><td>The PHP Driver https://github.com/phpredis/phpredis</td><tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>Starting from version 3.4, Joomla already has a Redis cache management.
The student is expected to extend the actual cache and session management
allowing the storage with the NoSQL (mongodb, redis). As a wanted side effect, the code written (drivers) should became an easy starting point for developers, to write extensions that can store data on NoSQL databases.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>Joomla, PHP, SQL, Nosql, data model(relational, key-value, document), Redis, MongoDB, Github</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium to Hard</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:optimus4joomla@gmail.com Nicola Galgano], [mailto:theachalaggarwal@gmail.com Achal Aggarwal]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project VI: Improve Acceptance Tests with PageObjects ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Joomla! currently does not have a viable system test coverage. That leads to regression bugs all the time. The project needs acceptance tests urgently. Using PageObjects as the main concept in this test class will enable us to re-use the tests in future versions, thus to provide better backward compatibility between major versions.
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>Coverage of the backend pages with PageObjects, Coverage of core frontend pages with PageObjects, A reasonable coverage of the backend with system tests
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>PHP, OOP. Basic knowledge about Docker and CodeCeption would be an advantage.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Easy</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:nbraczek@bsds.de Niels Braczek], [mailto:yves@compojoom.com Yves Hoppe]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project VII: Create Menu Item From Article or Other Component ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Return to the old option to Link Menu (V! 1.0.11) facilitating the creation of menus from the creation of an article. Bolder would allow this menu created from other components, such as index search, contact, and even extensions.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>1. Could be a plugin, with an option to choose which parent menu item and the specific content would be linked.
2. To save the item, add the field to the menu.

3. There could be a inputText to enter the title menu
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>PHP, OOP, Javascript
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Easy</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:pedrorenan@gmail.com Pedro Renan], [mailto:ittoufiq@gmail.com Md. Toufiqur Rahman], [mailto:peter.martin@community.joomla.org Peter Martin]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project VIII: Browser Automated Tests for Joomla! CMS (covering Users and Content features) ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>The idea behind the project is to create the system tests for joomla User Management and Content features(For Joomla 3.x). The suggested technology for developing the tests layer is the Codeception Open Source Testing Framework (more info at http://codeception.com).

Test will have to cover the User cases of: creating, editing, removing, publishing articles of content and being modified by different user roles. Also the student is asked to create the integration tests that links the Administrator, the Frontend (by creating menu items) and the Modules and Plugins applications that are related to the Users and Content Features. For example: create an article in frontend, listing all the featured articles, show the articles of an specific category or create a menu item that links to an article.

Joomla is a Mobile Ready CMS, therefore the tests will have to cover different screen resolutions and the different positions of the elements.

The student will have to study the old system tests structure built in the Nearsoft PHP Library and propose a new structure for testing the Joomla Core. The resulting tests need to accomplish the goal of being easily maintainable while being well architectured dividing the responsibilities in scenarios, Pages and Step objects. The mentors will provide the student with code samples that will help the student to achieve the mentioned goals.

To read more about using Codeception with Joomla! Read here: https://docs.joomla.org/Testing_Joomla_Extensions_with_Codeception

More details about the project at https://groups.google.com/d/msg/jgsoc-2016/nzLDqY-chYA/V6ByOHalBQAJ
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>At the end of the project the student should create a Pull request against the Joomla-cms repository (https://github.com/joomla/joomla-cms) providing the system tests for the Users and Content features.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>PHP, object-oriented programming, Joomla CMS (from a user point of view), HTML and basic Git usage.

Value will be given to these candidates that have basic understanding of Selenium, xPath, Codeception framework, Javascript and Knowledge on linux console and Docker Containers.

Is a must for being a candidate for this project to proof that you have been able to run in your local machine the current Webdriver Test Suite. See instructions at https://github.com/joomla-extensions/weblinks#tests

</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium to Hard</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:javier.gomez@community.joomla.org Javier Gomez], [mailto:yves@compojoom.com Yves Hoppe]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project IX: One-click Multiple Images Adding Into Article ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Current workflow for adding images to article is costly for human time and efforts:
1. Before you start create article you have to create folder for new images in Media Manager.

2. At article creating screen you need to open extra window to upload images in necessary folder or in root of media folder.

3. You can upload multiple files here, but you can't paste more than one image into article, so if you have upload image in path like /2015/02/20/something - you have navigate into this folder again.

And now multiple it on ~10 articles in day.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>One-click multiple images adding into article.
Image folders should be created automatically by template.
And as result, end-users are not wasting time with files/folders/pop-ups juggling.
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>Usability, user experience, programmer-free outlook on life.
PHP, AJAX, Jquery, cross-browser JavaScript.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:shams.bd71@gmail.com Abu Huraira Bin Aman], [mailto:rishi_vishwakarma@hotmail.com Rishi Vishwakarma], [mailto:rob@pollen-8.co.uk Rob Clayburn]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project X: JavaScript Unit Tests ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Joomla uses a collection of custom written JavaScript libraries for its core functionality. This keeps on increasing and it makes it difficult to do enhancements and upgrades for these libraries without conducting extensive manual testing for dependent features in CMS. The goal of this project is to write unit tests for custom JavaScript libraries in Joomla and integrate it with its build system(Travis) to build a solid foundation for future enhancements of these libraries.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>Setup a JavaScript Unit Testing framework and a test runner to evaluate Unit Tests on Travis Build. Write Unit Tests to increase the test coverage above 90% for custom JavaScript libraries written for Joomla. Document JavaScript Unit Test Guide for Joomla.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>Understanding Unit Testing, Unit Testing Frameworks for JavaScript, JavaScript, jQuery, PHP, Travis CI</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium to hard</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:ashanf@99x.lk Ashan Fernando]</td>
</tr>
</table>
[[Image:Gsoc2016.png|50px|center]]

----

====Project XI: Introduction of Accessibility Standards & Code ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Joomla has a lot of accessibility capabilities for visually impaired users but there are a lot of areas where it can improve. Currently there is a lot of work to bring the CMS to WCAG 2.0 AA standards and bringing it closer to being a listed ATAG 2.0 resource for content publishing.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td> All templates distributed in Joomla to meet WCAG 2.0 AA standards
Template and coding guidelines to help developers create standards compliant code that will meet WCAG 2.0 AA</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>Strong front end development skills, bootstrap 2, JS, Joomla dev & accessibility testing and coding skills.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium to Hard</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:akarawuth.t@gmail.com Akarawuth Tamrareang], [mailto:Gunjan.ce2009@gmail.com Gunjan Patel]</td>
</tr>
</table>
[[Image:Gsoc2016.png|50px|center]]
----

=== Extension Ideas ===

====Project XI: Larger Joomla ACL publication ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Add to new levels publishing stream: author, reviewer, publisher, supervisor. Where you can determine the profiles, according to the category of the content. essential tool for large projects where there are various teams and responsibilities.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>1. A publishing stream screen, linked to categories (com_categories)<br>
2. Adding action buttons Approve / Review<br>
3. Flag for the backend module, to-do items for review / approval, according to the user profile
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>php, oo, javascript</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:roberson.augusto@gmail.com Roberson Augusto], [mailto:nbraczek@bsds.de Niels Braczek]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project XII: Recording actions logs, accessible by super admin ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Store the tasks performed by any user, informing those who did, where did when did and what made within the project.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>A component to map The Croods within the CMS, with filters by date, extension and user</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>php, oo, javascript</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:allan.walker@community.joomla.org Allan Walker], [mailto:llewellyn@vdm.io Llewellyn]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

====Project XIII: Double marking position for modules ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>Allow a module to be used in two or more menu items, but in different positions. often módulso need to be duplicated in order to be used in more than one menu item and / or home site. allowing tow module and position + menu reduce the amount of unnecessary duplication</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>Option interface to change the position, the selected menu item</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>php, oo, javascript</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium to hard</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Possible mentors:'''</th>
</tr>
<tr>
<td>NA</td>
</tr>
</table>
[[Image:Gsoc2016.png|50px|center]]
----

[[Category:Google Summer of Code 2016]]

====Project XIV: Improve Joomla front and back-end performance through better compatibility with reverse proxies and PageSpeed Module ====

<table border="0" style="width:100%">
<tr>
<th>'''Brief explanation:'''</th>
</tr>
<tr>
<td>The CMS Joomla has a good native cache system that improves back-end performance in order to accelerate the HTML generation by 2 to 4 times. With the help of third-party extensions, you can increase the front-end performance (e.g how fast the site seems to load to the user, as well as savings in file transfer), however such extensions can harm back-end performance.

Websites with Joomla CMS focused in high performance, with big amounts of traffic, or with the requirement of generating HTML in less than 100ms, usually use Joomla without performance-enhancing extensions, and implement those tweaks at the webserver level with the PageSpeed module. Furthermore, it is common to employ a caching system like Varnish (or similar) to do a complete ephemeral storage of the resulting HTML response. Such system is greatly appreciated

Joomla, by default (without third-party extensions), does not allow reverse proxy caching. With the use of extensions in Joomla it’s possible, however it's still not a trivial process nor a pleasant experience, and in some cases - in order to completely disable unnecessary features - might even require changing the core of Joomla, like disabling the use of sessions for guests and hit counts on articles.

This idea is about using the Joomla CMS for what it does best: managing content. To do this we need to trust the cache and HTML/CSS/JS/images optimization to the webserver, in order to allow Joomla to run even faster and spending less money with hosting and CPU time.
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Expected Results:'''</th>
</tr>
<tr>
<td>It is expected that - as an additional option and not by default - you make Joomla able to control the HTTP caching headers to set a different caching time to one or more reverse proxies, just as the cache time sent to the visitor's browser. This feature should obligatorily be tested and functional for the main reverse proxies that are typically used in the market. Ideally, but not necessarily required, compatibility with services that deliver HTML caching as a service (like possibly CloudFlare and Fastly ®) could also be sought.

If enabled, when a manager create, edit or delete Joomla articles, it will trigger an event to automatically detect major typically changed URLs (for example, the article page itself, the listing page of the categories and the site's homepage) and thereby allow immediate cache invalidation on those URLs, and on those URLs only, in order to reduce the Joomla administrator’s burden that has to manually invalidate each cached URL- which is a major discouraging aspect of the use of cache invalidation in itself. (Note: The CMS Joomla allows triggers, see https://docs.joomla.org/Plugin/Events)

As to these triggers, it is not required to implement the functionality in a way that automatically use these triggers to effectively invalidate the main reverse proxies’s cache, only allow - in the future - people can use this code base to extend this functionality. However, it tends to be interesting to choose at least one effective example, like Varnish-cache, so this functionality can be througly tested.

Compatibility with Pagespeed Module probably shouldn’t need special changes, but this project should be tested presuming the module is enabled. In case of incompatibilities with the default settings, the produced PHP code should work around these, or there should be produced specific documentation warning about the caveats. A good example of a PageSpeed-related change is to disable content optimizations inside the CMS for specific browsers, such as conversion of images to WEBP - which could provide a cached image that would not work on incompatible browsers.

In addition to the code produced, it is expected that the student create benchmarks comparing before-and-after performance, and also comparing your solution with the solutions using the old native Joomla Caching. At the end of the project, there will be required documentation on how to use the solution, including the provision of configuration suggestions that are relevant to the server, in order to achieve the expected result.

IMPORTANT: In additional improvements that changes the Joomla core, which are not needed when you have full page cache like the option to disable hit count in Joomla articles and session creation for guest users, the student will have help from mentors and the Joomla developer community to decide whether it’s worth being implemented. Both this, and other expected results, may change if a strong technical impediment is detected beyond the scope expected for a student during the GSoC period.
</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Knowledge Prerequisite:'''</th>
</tr>
<tr>
<td>It is recommended to already know how to use a POSIX-like operating system, and it is essential to know how to deal with the command line. You must also have previous knowledge in PHP.

It is not necessary to have prior knowledge with Joomla CMS itself, since this you can learn from us. It is also not required to have previous experience with reverse proxies and the PageSpeed Module, but you must be willing to learn about it, and be pro-active after initial support. Of course, you will have help from mentors in complex situations that will likely arise.

This is more of a DevOps project (https://en.wikipedia.org/wiki/DevOps) than a programmer-only idea. It will be less about just coding in PHP, and will be required to be capable of setting enviroments to test and benchmark the resulting performance. This can be a particularly good project depending on the area you want to work professionally, mainly because having such experience in this area is rar. Finally, it is expected that you have commitment to the idea and the Joomla community.</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Difficulty:'''</th>
</tr>
<tr>
<td>Medium to Hard</td>
</tr>
</table>
<table border="0" style="width:100%">
<tr>
<th>'''Mentors:'''</th>
</tr>
<tr>
<td>[mailto:emerson@alligo.com.br Emerson Rocha Luiz]</td>
</tr>
</table>

[[Image:Gsoc2016.png|50px|center]]
----

[https://groups.google.com/forum/#!forum/jgsoc-2016 For more information please see this mailing list discussion]

Testing Joomla Extensions with Codeception

2016-02-29T19:49:33Z

Javiparati: /* Running the Test */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder structure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder structure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-extensions/weblinks/ com_weblinks] (read about how to fork a repository at https://help.github.com/articles/fork-a-repo/)
# Git clone git@github.com:*your-github-profile-name*/com_weblinks.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Find the complete instructions for running Weblinks tests at: https://github.com/joomla-extensions/weblinks#tests

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.

Allowed locator mechanisms are:

<source lang="php">
- ['id' => 'xxx']
- ['name' => 'xxx']
- ['css' => 'xxx']
- ['xpath' => 'xxx']
- ['link' => 'xxx']
- ['class' => 'xxx']
</source>

More info: http://codeception.com/docs/modules/WebDriver#Locating-Elements

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','60',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 60 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

If a waitForText command takes over 10 seconds, it will much probably mean that something is not performing well. Maybe a non [[Testing Joomla Extensions with Codeception#Always_add_Strict_Locators_to_your_tests|Strict Locator]] is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

===Thoughts on Selenium IDE and the codeception Formatter===
Selenium IDE is a Firefox extension that allows to generate tests in a interactive way:

[[File:Seleniumide.png|thumbnail]]

One can use the [http://www.seleniumhq.org/projects/ide/ Selenium IDE] with the [https://addons.mozilla.org/en-US/firefox/addon/codeception-formatters/ codeception Formatter] to export the tests to Codeception Framework Format.

[[File:exportcodeception.png|thumbnail]]

Using the Selenium IDE to write the tests seems way easier than writing them in PHP (since you have immediate feedback on what's going on the page), but it also poses some issues.
For the most part the Joomla-Browser has functions that we can use to do standard stuff like login, logout etc. If we do our tests with the Selenium IDE we cannot use those and our tests get filled up with stuff that we have already abstracted.

There is still use of the Selenium IDE though, we could use it to create the tests for specific functionality. Like just writing an article, setting publish_up and publish_down dates and then saving. When we export the result with the codeception formatter we would have the necessary PHP and we can add the rest of the stuff for the test to be fully automated (login, navigate to page etc, then execute the exported test). This could speed the creation of tests and we could use non-developers for this kind of work. However this is easier said than done. Due to the Javascript that we use in Joomla simple tests are not that simple. For example clicking in the texteditor and writing text in it is not registered by the IDE since the editor is created by TinyMCE... A way to add text to the editor is to use

Command | runScript
Target | tinyMCE.get('text_area_id_not_iframe_id').setContent('Your text')

That is again a technical solution to a test that should have been easy in the first place.
We get into the same trouble with selecting a date out of a Calendar field. So at the end it seems pretty difficult for non-developers to create tests that we could use, because most of the steps recorded by the Selenium IDE won't work a second time.

If we find a way to make the work with Javascript elements on the page easier, then Selenium IDE could be a great tool that could help us write far more tests, than we currently have in a less time.

As far the codeception Formatter is concerned - it hasn't been updated in 2 years, but if we find out how to use the Selenium IDE extending the formatter and building on top of it shouldn't be a show stopper.

[[Category:Automated Testing]]
<noinclude>[[Category:Needs to be marked for translation]]</noinclude>

Testing Joomla Extensions with Codeception

2016-02-29T19:41:01Z

Javiparati: /* setting up the repository */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder structure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder structure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-extensions/weblinks/ com_weblinks] (read about how to fork a repository at https://help.github.com/articles/fork-a-repo/)
# Git clone git@github.com:*your-github-profile-name*/com_weblinks.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.

Allowed locator mechanisms are:

<source lang="php">
- ['id' => 'xxx']
- ['name' => 'xxx']
- ['css' => 'xxx']
- ['xpath' => 'xxx']
- ['link' => 'xxx']
- ['class' => 'xxx']
</source>

More info: http://codeception.com/docs/modules/WebDriver#Locating-Elements

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','60',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 60 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

If a waitForText command takes over 10 seconds, it will much probably mean that something is not performing well. Maybe a non [[Testing Joomla Extensions with Codeception#Always_add_Strict_Locators_to_your_tests|Strict Locator]] is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

===Thoughts on Selenium IDE and the codeception Formatter===
Selenium IDE is a Firefox extension that allows to generate tests in a interactive way:

[[File:Seleniumide.png|thumbnail]]

One can use the [http://www.seleniumhq.org/projects/ide/ Selenium IDE] with the [https://addons.mozilla.org/en-US/firefox/addon/codeception-formatters/ codeception Formatter] to export the tests to Codeception Framework Format.

[[File:exportcodeception.png|thumbnail]]

Using the Selenium IDE to write the tests seems way easier than writing them in PHP (since you have immediate feedback on what's going on the page), but it also poses some issues.
For the most part the Joomla-Browser has functions that we can use to do standard stuff like login, logout etc. If we do our tests with the Selenium IDE we cannot use those and our tests get filled up with stuff that we have already abstracted.

There is still use of the Selenium IDE though, we could use it to create the tests for specific functionality. Like just writing an article, setting publish_up and publish_down dates and then saving. When we export the result with the codeception formatter we would have the necessary PHP and we can add the rest of the stuff for the test to be fully automated (login, navigate to page etc, then execute the exported test). This could speed the creation of tests and we could use non-developers for this kind of work. However this is easier said than done. Due to the Javascript that we use in Joomla simple tests are not that simple. For example clicking in the texteditor and writing text in it is not registered by the IDE since the editor is created by TinyMCE... A way to add text to the editor is to use

Command | runScript
Target | tinyMCE.get('text_area_id_not_iframe_id').setContent('Your text')

That is again a technical solution to a test that should have been easy in the first place.
We get into the same trouble with selecting a date out of a Calendar field. So at the end it seems pretty difficult for non-developers to create tests that we could use, because most of the steps recorded by the Selenium IDE won't work a second time.

If we find a way to make the work with Javascript elements on the page easier, then Selenium IDE could be a great tool that could help us write far more tests, than we currently have in a less time.

As far the codeception Formatter is concerned - it hasn't been updated in 2 years, but if we find out how to use the Selenium IDE extending the formatter and building on top of it shouldn't be a show stopper.

[[Category:Automated Testing]]
<noinclude>[[Category:Needs to be marked for translation]]</noinclude>

Testing Joomla Extensions with Codeception

2015-11-03T12:39:49Z

Javiparati:

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.

Allowed locator mechanisms are:

<source lang="php">
- ['id' => 'xxx']
- ['name' => 'xxx']
- ['css' => 'xxx']
- ['xpath' => 'xxx']
- ['link' => 'xxx']
- ['class' => 'xxx']
</source>

More info: http://codeception.com/docs/modules/WebDriver#Locating-Elements

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','60',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 60 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

If a waitForText command takes over 10 seconds, it will much probably mean that something is not performing well. Maybe a non [[Testing Joomla Extensions with Codeception#Always_add_Strict_Locators_to_your_tests|Strict Locator]] is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

===Thoughts on Selenium IDE and the codeception Formatter===
Selenium IDE is a Firefox extension that allows to generate tests in a interactive way:

[[File:Seleniumide.png|thumbnail]]

One can use the [http://www.seleniumhq.org/projects/ide/ Selenium IDE] with the [https://addons.mozilla.org/en-US/firefox/addon/codeception-formatters/ codeception Formatter] to export the tests to Codeception Framework Format.

[[File:exportcodeception.png|thumbnail]]

Using the Selenium IDE to write the tests seems way easier than writing them in PHP (since you have immediate feedback on what's going on the page), but it also poses some issues.
For the most part the Joomla-Browser has functions that we can use to do standard stuff like login, logout etc. If we do our tests with the Selenium IDE we cannot use those and our tests get filled up with stuff that we have already abstracted.

There is still use of the Selenium IDE though, we could use it to create the tests for specific functionality. Like just writing an article, setting publish_up and publish_down dates and then saving. When we export the result with the codeception formatter we would have the necessary PHP and we can add the rest of the stuff for the test to be fully automated (login, navigate to page etc, then execute the exported test). This could speed the creation of tests and we could use non-developers for this kind of work. However this is easier said than done. Due to the Javascript that we use in Joomla simple tests are not that simple. For example clicking in the texteditor and writing text in it is not registered by the IDE since the editor is created by TinyMCE... A way to add text to the editor is to use

Command | runScript
Target | tinyMCE.get('text_area_id_not_iframe_id').setContent('Your text')

That is again a technical solution to a test that should have been easy in the first place.
We get into the same trouble with selecting a date out of a Calendar field. So at the end it seems pretty difficult for non-developers to create tests that we could use, because most of the steps recorded by the Selenium IDE won't work a second time.

If we find a way to make the work with Javascript elements on the page easier, then Selenium IDE could be a great tool that could help us write far more tests, than we currently have in a less time.

As far the codeception Formatter is concerned - it hasn't been updated in 2 years, but if we find out how to use the Selenium IDE extending the formatter and building on top of it shouldn't be a show stopper.

[[Category:Automated Testing]]
<noinclude>[[Category:Needs to be marked for translation]]</noinclude>

Testing Joomla Extensions with Codeception

2015-11-03T12:38:59Z

Javiparati: /* Always add Strict Locators to your tests */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.

Allowed locator mechanisms are:

<source lang="php">
- ['id' => 'xxx']
- ['name' => 'xxx']
- ['css' => 'xxx']
- ['xpath' => 'xxx']
- ['link' => 'xxx']
- ['class' => 'xxx']
</source>

More info: http://codeception.com/docs/modules/WebDriver#Locating-Elements

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','60',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 60 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

If a waitForText command takes over 10 seconds, it will much probably mean that something is not performing well. Maybe a non [[Testing Joomla Extensions with Codeception#Always_add_Strict_Locators_to_your_tests|Strict Locator]] is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

===Thoughts on Selenium IDE and the codeception Formatter===
Selenium IDE is a Firefox extension that allows to generate tests in a interactive way:

[[File:Seleniumide.png|thumbnail]]

One can use the [http://www.seleniumhq.org/projects/ide/ Selenium IDE] with the [https://addons.mozilla.org/en-US/firefox/addon/codeception-formatters/ codeception Formatter] to export the tests to Codeception Framework Format.

[[File:exportcodeception.png|thumbnail]]

Using the Selenium IDE to write the tests seems way easier than writing them in PHP (since you have immediate feedback on what's going on the page), but it also poses some issues.
For the most part the Joomla-Browser has functions that we can use to do standard stuff like login, logout etc. If we do our tests with the Selenium IDE we cannot use those and our tests get filled up with stuff that we have already abstracted.

There is still use of the Selenium IDE though, we could use it to create the tests for specific functionality. Like just writing an article, setting publish_up and publish_down dates and then saving. When we export the result with the codeception formatter we would have the necessary PHP and we can add the rest of the stuff for the test to be fully automated (login, navigate to page etc, then execute the exported test). This could speed the creation of tests and we could use non-developers for this kind of work. However this is easier said than done. Due to the Javascript that we use in Joomla simple tests are not that simple. For example clicking in the texteditor and writing text in it is not registered by the IDE since the editor is created by TinyMCE... A way to add text to the editor is to use

Command | runScript
Target | tinyMCE.get('text_area_id_not_iframe_id').setContent('Your text')

That is again a technical solution to a test that should have been easy in the first place.
We get into the same trouble with selecting a date out of a Calendar field. So at the end it seems pretty difficult for non-developers to create tests that we could use, because most of the steps recorded by the Selenium IDE won't work a second time.

If we find a way to make the work with Javascript elements on the page easier, then Selenium IDE could be a great tool that could help us write far more tests, than we currently have in a less time.

As far the codeception Formatter is concerned - it hasn't been updated in 2 years, but if we find out how to use the Selenium IDE extending the formatter and building on top of it shouldn't be a show stopper.

<noinclude>[[Category:Needs to be marked for translation]]</noinclude>

File:Exportcodeception.png

2015-11-01T12:00:43Z

Javiparati: Selenium IDE export tool to generate Codeception tests

== Summary ==
Selenium IDE export tool to generate Codeception tests
== Licensing ==
{{JEDL}}

File:Seleniumide.png

2015-11-01T11:59:48Z

Javiparati: Selenium IDE tool for testing in Firefox

== Summary ==
Selenium IDE tool for testing in Firefox
== Licensing ==
{{JEDL}}

Testing Joomla Extensions with Codeception

2015-11-01T11:58:43Z

Javiparati: /* Thoughts on Selenium IDE and the codeception Formatter */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.

Allowed locator mechanisms are:

<source lang="php">
- ['id' => 'xxx']
- ['name' => 'xxx']
- ['css' => 'xxx']
- ['xpath' => 'xxx']
- ['link' => 'xxx']
- ['class' => 'xxx']
</source>

[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','60',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 60 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

If a waitForText command takes over 10 seconds, it will much probably mean that something is not performing well. Maybe a non [[Testing Joomla Extensions with Codeception#Always_add_Strict_Locators_to_your_tests|Strict Locator]] is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

===Thoughts on Selenium IDE and the codeception Formatter===
Selenium IDE is a Firefox extension that allows to generate tests in a interactive way:

[[File:Seleniumide.png|thumbnail]]

One can use the [http://www.seleniumhq.org/projects/ide/ Selenium IDE] with the [https://addons.mozilla.org/en-US/firefox/addon/codeception-formatters/ codeception Formatter] to export the tests to Codeception Framework Format.

[[File:exportcodeception.png|thumbnail]]

Using the Selenium IDE to write the tests seems way easier than writing them in PHP (since you have immediate feedback on what's going on the page), but it also poses some issues.
For the most part the Joomla-Browser has functions that we can use to do standard stuff like login, logout etc. If we do our tests with the Selenium IDE we cannot use those and our tests get filled up with stuff that we have already abstracted.

There is still use of the Selenium IDE though, we could use it to create the tests for specific functionality. Like just writing an article, setting publish_up and publish_down dates and then saving. When we export the result with the codeception formatter we would have the necessary PHP and we can add the rest of the stuff for the test to be fully automated (login, navigate to page etc, then execute the exported test). This could speed the creation of tests and we could use non-developers for this kind of work. However this is easier said than done. Due to the Javascript that we use in Joomla simple tests are not that simple. For example clicking in the texteditor and writing text in it is not registered by the IDE since the editor is created by TinyMCE... A way to add text to the editor is to use

Command | runScript
Target | tinyMCE.get('text_area_id_not_iframe_id').setContent('Your text')

That is again a technical solution to a test that should have been easy in the first place.
We get into the same trouble with selecting a date out of a Calendar field. So at the end it seems pretty difficult for non-developers to create tests that we could use, because most of the steps recorded by the Selenium IDE won't work a second time.

If we find a way to make the work with Javascript elements on the page easier, then Selenium IDE could be a great tool that could help us write far more tests, than we currently have in a less time.

As far the codeception Formatter is concerned - it hasn't been updated in 2 years, but if we find out how to use the Selenium IDE extending the formatter and building on top of it shouldn't be a show stopper.

<noinclude>[[Category:Needs to be marked for translation]]</noinclude>

Testing Joomla Extensions with Codeception

2015-10-31T11:55:15Z

Javiparati: /* Always add Strict Locators to your tests */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.

Allowed locator mechanisms are:

<source lang="php">
- ['id' => 'xxx']
- ['name' => 'xxx']
- ['css' => 'xxx']
- ['xpath' => 'xxx']
- ['link' => 'xxx']
- ['class' => 'xxx']
</source>

[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','60',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 60 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

If a waitForText command takes over 10 seconds, it will much probably mean that something is not performing well. Maybe a non [[Testing Joomla Extensions with Codeception#Always_add_Strict_Locators_to_your_tests|Strict Locator]] is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

<noinclude>[[Category:Needs to be marked for translation]]</noinclude>

Testing Joomla Extensions with Codeception

2015-10-31T11:54:26Z

Javiparati: /* Always add Strict Locators to your tests */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.

Allowed locator mechanisms are:

- ['id' => 'xxx']
- ['name' => 'xxx']
- ['css' => 'xxx']
- ['xpath' => 'xxx']
- ['link' => 'xxx']
- ['class' => 'xxx']

[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','60',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 60 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

If a waitForText command takes over 10 seconds, it will much probably mean that something is not performing well. Maybe a non [[Testing Joomla Extensions with Codeception#Always_add_Strict_Locators_to_your_tests|Strict Locator]] is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

<noinclude>[[Category:Needs to be marked for translation]]</noinclude>

Testing Joomla Extensions with Codeception

2015-10-28T09:28:50Z

Javiparati: /* How much time should I wait for an Element or Text? */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.
[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','60',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 60 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

If a waitForText command takes over 10 seconds, it will much probably mean that something is not performing well. Maybe a non [[Testing Joomla Extensions with Codeception#Always_add_Strict_Locators_to_your_tests|Strict Locator]] is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

<noinclude>[[Category:Needs to be marked for translation]]</noinclude>

Code sprints

2015-10-14T12:08:20Z

Javiparati:

<noinclude><languages /></noinclude>

<translate>

A code sprint is a dedicated session in which a group of volunteers come together at a geographic location to work on code for the Joomla project. Examples of code sprint sessions could include UI/UX improvements, working on new features, or long term planning and architecture work. Typically, six to ten experienced individuals will be brought together for two days for these events. If you wish to form your own sprint then read the [[S:MyLanguage/Joomla:Sprint_Policy|policy]]
</translate>

<translate>

The code sprints are organised by the Joomla community together with the Production Leadership Team. These events are supported by the OpenSourceMatters and other sponsors.
</translate>

<translate>

Code Sprints in 2013:
* '''Rapid Application Development Code Sprint''', July 2013, Pistoia, Italy
* '''Code stability and bug triage Code Sprint''', Aug 2013, Nashville, Tennessee, USA. More info:
</translate> http://community.joomla.org/blogs/leadership/1757-call-for-participants-for-code-sprint.html

<translate>

Code Sprints in 2014:
* '''Architecture Sprint''', Feb 8-9, San Jose, California, USA.
* '''Bug Clean Up Sprint''', July 26-27, More info: http://magazine.joomla.org/issues/issue-aug-2014/item/2228-joomla-bug-sprint-in-manchester
* '''Code Style Code Sprint''', Oct 11-12, Madrid, Spain. More info at: http://magazine.joomla.org/issues/issue-nov-2014/item/2353-two-joomla-code-sprints
* '''Code Testing Code Sprint''', Oct 14, Montabaur, Germany. More info at: http://thephp.cc/viewpoints/blog/2014/10/joomla-phpunit-code-sprint
</translate>

Code Sprints in 2015:
* '''Joomla 4 Architecture Sprint''', July 10-12, Odense, Denmark. More info at: http://volunteers.joomla.org/reports/115-joomla-4-architecture-sprint-odense-dk
* '''Joomla 4 UX and Architecture Sprint''', October 10-12, Athens, Greece.
* '''Joomla! Automated Testing Code Sprint''', October 28th - November 2nd, Karlsruhe, Germany.
<translate>

[[Category:Events]]
</translate>

Joomla info page/es-ES

2015-10-08T12:11:36Z

Javiparati: removing http://joomlaspanish.org since is not anymore available

= Spanish =

== ¿Qué es Joomla? ==
Joomla es un premiado sistema de Gestión de Contenidos (CMS), que permite crear sitios Web y poderosas aplicaciones online. Muchos aspectos, incluyendo su fácil uso y extensibilidad han convertido a Joomla! en el software para Web más popular. Y lo mejor de todo, Joomla es Software Libre disponible gratuitamente para todo el mundo. Entre los beneficios de Joomla se incluye:

* Fácil instalación
* Simple mantenimiento del web
* Seguridad y estabilidad
* Potentes extensiones comerciales y gratuitas
* Una enorme cantidad de plantillas para cambiar fácilmente el look de tu web.

Tienes más información sobre Joomla! en español [http://docs.joomla.org/Joomla_brochure/es-ES en este otro artículo de la documentación].

== ¿Dónde conseguir Joomla? ==
* Descarga Joomla! desde los [http://www.joomla.org/download.html repositorios oficiales].
* Descarga los paquetes de idioma español de los [http://community.joomla.org/translations.html grupos de traducción acreditados] desde aquí:
** [http://joomlacode.org/gf/project/jtranslation/frs/?action=FrsReleaseBrowse&frs_package_id=30 Paquetes de la rama 1.5.x]
** [http://joomlacode.org/gf/project/jtranslation1_6/frs/?action=FrsReleaseBrowse&frs_package_id=5597 Paquetes de la rama 2.5.x]
** [http://joomlacode.org/gf/project/jtranslation3_x/frs/?action=FrsReleaseBrowse&frs_package_id=6445 Paquetes de la rama 3.0.x]
* Otras traducciones
** [http://joomlacode.org/gf/project/spanishlanguage/frs/ Traducciones más antiguas del grupo acreditado anterior (incluye traducciones de la rama 1.0.x)]

== ¿Dónde descargar extensiones? ==
* Descarga extensiones en: http://extensions.joomla.org/

== ¿Dónde conseguir documentación para Joomla? ==
* Documentación en inglés: http://docs.joomla.org/

== ¿Dónde conseguir soporte/ayuda para Joomla? ==
* Soporte gratuito en Inglés: http://forum.joomla.org/
* Soporte gratuito en Español:
** http://forum.joomla.org/viewforum.php?f=24
** http://magazine.joomla.org/international-stories-all/articles-in-spanish-all
* Soporte gratuito en lugares no oficiales:
** http://foro.comunidadjoomla.org
* Soporte comercial: http://resources.joomla.org/ (website en Inglés)

== Eventos regionales / Joomladays ==
Las comunidades locales organizan eventos Joomla! conocidos como ''Joomla!Days'' por todo el mundo. Un Joomla Day es un evento creado exclusivamente para los usuarios de Joomla! y sus proyectos relacionados. Habitualmente tienen una audiencia regional. Más información en: http://events.joomla.org/joomla-days.html

== Joomla User Groups (JUG) ==
Los Grupos de usuarios de Joomla (JUG) son una manera magnífica de conocer gente, conseguir ayuda para un proyecto, o compartir las experiencias con otros usuarios de Joomla. Joomla! está en todos los lugares del mundo así que revisa si ya existe algún JUG en tu zona. En caso contrario, ¿Por qué no creas uno?

* JUGs en Centro América: http://community.joomla.org/user-groups/central-america.html
* JUGs en el Caribe: http://community.joomla.org/user-groups/caribbean.html
* JUGs en Sud América: http://community.joomla.org/user-groups/south-america.html
* JUGs España: http://community.joomla.org/user-groups/europe/spain.html

* Preguntas frecuentes JUG: http://community.joomla.org/jug-faq-spanish.html

== ¿Cómo puedes apoyar a Joomla!? ==
* Responde dudas de otras personas en los foros
* Escribe o traduce un tutorial o documentación
* Desarrolla una Extensión o una plantilla de diseño
* Testea y comunica los errores que encuentres
* Únete a un equipo de trabajo Joomla!
* Colabora en la organización y participa en los eventos Joomla!
* Apoya económicamente o de otras maneras: http://contribute.joomla.org/

Testing Joomla Extensions with Codeception

2015-09-28T09:19:21Z

Javiparati: /* Do not leave spaces between parameters in Cepts */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.
[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','30',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 30 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

A waitForText over 10 seconds will definitely mean that something is not performing well. Maybe a non strict Locator is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Write complex locator VS. modifying the output of the tested website===
Sometimes we need to write a very complex xpath to locate a element in the page, for example:

$I->click(['xpath' => "//*[@id=\"menuList\"]/tbody/tr/td[2]/a[contains(text(), 'weblink')"])

wouldn't be much better to write something like this instead?

$I->click(['class' => "lc-menu_item_type_weblinks"])

When you find yourself writting a very complex locator in a test, is maybe because the markup of the Website is wrong. For this cases, is better to stop writing the test and reconsider the possibility of modifying the website that we are testing. There is nothing that prevents us to improve Joomla markup. Actually is the other way arround, with these fixes we are probably making Joomla more accessible.
We have had experiences in the past, see for example this issue: https://github.com/joomla/joomla-cms/issues/7207.

In conclusion is much more convenient to add just a simple class to the element to easily locate it instead of becoming mad finding the right xPath. Remind that is important that our tests are readable, and that has to do with using readable locators.

In order to simplify locators used in Acceptance tests we add special locator classes into HTML of web pages. So not to confuse them with classes needed by CSS or JavaScript we use '''lc-''' prefix. Thus, if you find locator to be to complex, it would be much easier to edit HTML and add a new class into it.

$I->click('class' => "lc-comment-delete');

Where ''lc'' stands for ''locator''.

Is important that the rest of Joomla coders know that this '''lc-''' prefix is used by the tests to prevent anyone from removing it.

This recommendation was originally suggested by Davert (the creator of Codeception) at http://phptest.club/t/codeception-tips-tricks/14/8.

J3.x:Making a Language Pack for Joomla

2015-07-29T14:54:53Z

Javiparati: Add FAQ to language package creation

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=3.x|comment=<translate>
series</translate>}}</noinclude>
{{-}}
{{RightTOC}}
<translate>==How to create localized CORE language packs== </translate>
<translate>
===Notes=== 
* ALL FILES MUST BE SAVED AS UTF8 NO BOM (for non-ascii glyphs as in accented letters, etc.)


* The [http://extensions.joomla.org/extensions/languages/language-edition/17755 Localise] component may help you create and update the ini files


* For 3rd party extensions self-contained ini files installation in Joomla 2.5, see [[S:MyLanguage/J2.5:Making non-core language packs|J2.5:Making non-core language packs]]


* For Joomla 2.5 core language packs, see [[S:MyLanguage/J2.5:Making a Language Pack for Joomla|J2.5:Making a Language Pack for Joomla!]]


* As of Joomla! 3.2.0, en-GB is always loading first. Therefore if a string is missing or if there is a parsing error in a language pack, the English value will be displayed.


* Current Joomla development can be fetched from the [https://github.com/joomla/joomla-cms Home of the Joomla! Content Management System at Github]
</translate>

<translate>
==Full language packs== 
</translate>
<translate>

'''* <code>fr-FR<code> is taken as an example of language prefix.'''
A full language pack will contain translations for site and admin parts.


# In the case of a '''FULL''' pack, the package is composed of 3 files, then zipped.
#* <code>pkg_fr-FR.xml</code>
#* <code>site_fr-FR.zip</code>
#* <code>admin_fr-FR.zip</code>
# Naming of the pack
#* '''fr-FR_joomla_lang_full_3.4.1v1.zip'''
# Files required for partial deletion
#* each pack should include a <code>fr-FR.lib_joomla.ini</code> and a <code>fr-FR.localise.php</code> to cope for deletion of site or admin pack by the user.
#* '''IMPORTANT''': Since some administrator ini files are necessary in front-end and some changes were brought in the loading of the plugin ini files, it is always necessary to include some admin part in the final pack, even for a ''''site-only'''' pack. See below [[#The Site-only pack|The Site-only pack]]
</translate>

<translate>===A pkg_fr-FR.xml file=== </translate>

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<extension type="package" version="3.4" method="upgrade"> <! method="upgrade" is compulsory since 3.4 -->
<name>French_fr-FR</name>
<packagename>fr-FR</packagename> 
<version>3.4.1.1</version> 
<creationDate>03/03/2015</creationDate> 
<author>French translation team : joomla.fr</author> 
<authorEmail>traduction@joomla.fr</authorEmail> 
<authorUrl>http://joomla.fr</authorUrl> 
<copyright>Copyright (C) 2005 - 2015 Joomla.fr and Open Source Matters, Inc. All rights reserved.</copyright>
<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
<url></url>
<packager></packager>
<packagerurl></packagerurl>
<description><![CDATA[<div style="text-align:left;">
<h3>Joomla! 3.4.1 Full French (fr-FR) Language Package - Version 3.4.1v1</h3>
<h3>Paquet de langue Joomla! 3.4.1 français (fr-FR) complet - Version 3.4.1v1</h3>
</div>]]></description>
<files>
<file type="language" client="site" id="fr-FR">site_fr-FR.zip</file>
<file type="language" client="administrator" id="fr-FR">admin_fr-FR.zip</file>
</files>
<updateservers>
<server type="collection" priority="1" name="Accredited Joomla! Translations">http://update.joomla.org/language/translationlist_3.xml</server>
</updateservers>
</extension>
</source>

<translate>

Note: TinyMCE files are no more needed for 3.2. They are now shipped with core. If your language is missing, please contact the Translation Team coordination.
</translate>

<translate>
===One zip per client (i.e. site and admin)=== 


* <code>site_fr-FR.zip</code>
* <code>admin_fr-FR.zip</code>


Content of the client's zip (example below is for admin)
</translate>

<translate>
====an install.xml ==== 
Example for admin
</translate>

<source lang="xml"
<?xml version="1.0" encoding="utf-8"?>
<extension version="3.4" client="administrator" type="language" method="upgrade"> // change to client="site" if site pack
<name>French (fr-FR)</name>
<tag>fr-FR</tag>
<version>3.4.1.1</version>
<creationDate>15/05/2013</creationDate>
<author>French translation team : joomla.fr</author>
<authorEmail>traduction@joomla.fr</authorEmail>
<authorUrl>www.joomla.fr</authorUrl>
<copyright>Copyright (C) 2005 - 2013 joomla.fr et Open Source Matters. Tous droits réservés</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<description>fr-FR administrator language</description>
<files>
<filename>index.html</filename>
<filename>fr-FR.com_admin.ini</filename>
<filename>fr-FR.com_admin.sys.ini</filename>
<filename>fr-FR.com_banners.ini</filename>
<filename>fr-FR.com_banners.sys.ini</filename>
<filename>fr-FR.com_ajax.ini</filename>
<filename>fr-FR.com_ajax.sys.ini</filename>
<filename>fr-FR.com_cache.ini</filename>
<filename>fr-FR.com_cache.sys.ini</filename>
<filename>fr-FR.com_categories.ini</filename>
<filename>fr-FR.com_categories.sys.ini</filename>
<filename>fr-FR.com_checkin.ini</filename>
<filename>fr-FR.com_checkin.sys.ini</filename>
<filename>fr-FR.com_config.ini</filename>
<filename>fr-FR.com_config.sys.ini</filename>
<filename>fr-FR.com_contact.ini</filename>
<filename>fr-FR.com_contact.sys.ini</filename>
<filename>fr-FR.com_content.ini</filename>
<filename>fr-FR.com_content.sys.ini</filename>
<filename>fr-FR.com_contenthistory.ini</filename>
<filename>fr-FR.com_contenthistory.sys.ini</filename>
<filename>fr-FR.com_cpanel.ini</filename>
<filename>fr-FR.com_cpanel.sys.ini</filename>
<filename>fr-FR.com_finder.ini</filename>
<filename>fr-FR.com_finder.sys.ini</filename>
<filename>fr-FR.com_installer.ini</filename>
<filename>fr-FR.com_installer.sys.ini</filename>
<filename>fr-FR.com_joomlaupdate.ini</filename>
<filename>fr-FR.com_joomlaupdate.sys.ini</filename>
<filename>fr-FR.com_languages.ini</filename>
<filename>fr-FR.com_languages.sys.ini</filename>
<filename>fr-FR.com_login.ini</filename>
<filename>fr-FR.com_login.sys.ini</filename>
<filename>fr-FR.com_mailto.sys.ini</filename>
<filename>fr-FR.com_media.ini</filename>
<filename>fr-FR.com_media.sys.ini</filename>
<filename>fr-FR.com_menus.ini</filename>
<filename>fr-FR.com_menus.sys.ini</filename>
<filename>fr-FR.com_messages.ini</filename>
<filename>fr-FR.com_messages.sys.ini</filename>
<filename>fr-FR.com_modules.ini</filename>
<filename>fr-FR.com_modules.sys.ini</filename>
<filename>fr-FR.com_newsfeeds.ini</filename>
<filename>fr-FR.com_newsfeeds.sys.ini</filename>
<filename>fr-FR.com_plugins.ini</filename>
<filename>fr-FR.com_plugins.sys.ini</filename>
<filename>fr-FR.com_postinstall.ini</filename>
<filename>fr-FR.com_postinstall.sys.ini</filename>
<filename>fr-FR.com_redirect.ini</filename>
<filename>fr-FR.com_redirect.sys.ini</filename>
<filename>fr-FR.com_search.ini</filename>
<filename>fr-FR.com_search.sys.ini</filename>
<filename>fr-FR.com_tags.ini</filename>
<filename>fr-FR.com_tags.sys.ini</filename>
<filename>fr-FR.com_templates.ini</filename>
<filename>fr-FR.com_templates.sys.ini</filename>
<filename>fr-FR.com_users.ini</filename>
<filename>fr-FR.com_users.sys.ini</filename>
<filename>fr-FR.com_weblinks.ini</filename>
<filename>fr-FR.com_weblinks.sys.ini</filename>
<filename>fr-FR.com_wrapper.ini</filename>
<filename>fr-FR.com_wrapper.sys.ini</filename>
<filename>fr-FR.css</filename> 
<filename>fr-FR.ini</filename>
<filename>fr-FR.lib_joomla.ini</filename>
<filename>fr-FR.localise.php</filename>
<filename>fr-FR.mod_custom.ini</filename>
<filename>fr-FR.mod_custom.sys.ini</filename>
<filename>fr-FR.mod_feed.ini</filename>
<filename>fr-FR.mod_feed.sys.ini</filename>
<filename>fr-FR.mod_latest.ini</filename>
<filename>fr-FR.mod_latest.sys.ini</filename>
<filename>fr-FR.mod_logged.ini</filename>
<filename>fr-FR.mod_logged.sys.ini</filename>
<filename>fr-FR.mod_login.ini</filename>
<filename>fr-FR.mod_login.sys.ini</filename>
<filename>fr-FR.mod_menu.ini</filename>
<filename>fr-FR.mod_menu.sys.ini</filename>
<filename>fr-FR.mod_multilangstatus.ini</filename>
<filename>fr-FR.mod_multilangstatus.sys.ini</filename>
<filename>fr-FR.mod_popular.ini</filename>
<filename>fr-FR.mod_popular.sys.ini</filename>
<filename>fr-FR.mod_quickicon.ini</filename>
<filename>fr-FR.mod_quickicon.sys.ini</filename>
<filename>fr-FR.mod_stats_admin.ini</filename>
<filename>fr-FR.mod_stats_admin.sys.ini</filename>
<filename>fr-FR.mod_status.ini</filename>
<filename>fr-FR.mod_status.sys.ini</filename>
<filename>fr-FR.mod_submenu.ini</filename>
<filename>fr-FR.mod_submenu.sys.ini</filename>
<filename>fr-FR.mod_title.ini</filename>
<filename>fr-FR.mod_title.sys.ini</filename>
<filename>fr-FR.mod_toolbar.ini</filename>
<filename>fr-FR.mod_toolbar.sys.ini</filename>
<filename>fr-FR.mod_version.ini</filename>
<filename>fr-FR.mod_version.sys.ini</filename>
<filename>fr-FR.plg_authentication_cookie.ini</filename>
<filename>fr-FR.plg_authentication_cookie.sys.ini</filename>
<filename>fr-FR.plg_authentication_gmail.ini</filename>
<filename>fr-FR.plg_authentication_gmail.sys.ini</filename>
<filename>fr-FR.plg_authentication_joomla.ini</filename>
<filename>fr-FR.plg_authentication_joomla.sys.ini</filename>
<filename>fr-FR.plg_authentication_ldap.ini</filename>
<filename>fr-FR.plg_authentication_ldap.sys.ini</filename>
<filename>fr-FR.plg_captcha_recaptcha.ini</filename>
<filename>fr-FR.plg_captcha_recaptcha.sys.ini</filename>
<filename>fr-FR.plg_content_emailcloak.ini</filename>
<filename>fr-FR.plg_content_emailcloak.sys.ini</filename>
<filename>fr-FR.plg_content_finder.ini</filename>
<filename>fr-FR.plg_content_finder.sys.ini</filename>
<filename>fr-FR.plg_content_joomla.ini</filename>
<filename>fr-FR.plg_content_joomla.sys.ini</filename>
<filename>fr-FR.plg_content_loadmodule.ini</filename>
<filename>fr-FR.plg_content_loadmodule.sys.ini</filename>
<filename>fr-FR.plg_content_pagebreak.ini</filename>
<filename>fr-FR.plg_content_pagebreak.sys.ini</filename>
<filename>fr-FR.plg_content_pagenavigation.ini</filename>
<filename>fr-FR.plg_content_pagenavigation.sys.ini</filename>
<filename>fr-FR.plg_content_vote.ini</filename>
<filename>fr-FR.plg_content_vote.sys.ini</filename>
<filename>fr-FR.plg_editors_codemirror.ini</filename>
<filename>fr-FR.plg_editors_codemirror.sys.ini</filename>
<filename>fr-FR.plg_editors_none.ini</filename>
<filename>fr-FR.plg_editors_none.sys.ini</filename>
<filename>fr-FR.plg_editors_tinymce.ini</filename>
<filename>fr-FR.plg_editors_tinymce.sys.ini</filename>
<filename>fr-FR.plg_editors-xtd_article.ini</filename>
<filename>fr-FR.plg_editors-xtd_article.sys.ini</filename>
<filename>fr-FR.plg_editors-xtd_image.ini</filename>
<filename>fr-FR.plg_editors-xtd_image.sys.ini</filename>
<filename>fr-FR.plg_editors-xtd_pagebreak.ini</filename>
<filename>fr-FR.plg_editors-xtd_pagebreak.sys.ini</filename>
<filename>fr-FR.plg_editors-xtd_readmore.ini</filename>
<filename>fr-FR.plg_editors-xtd_readmore.sys.ini</filename>
<filename>fr-FR.plg_extension_joomla.ini</filename>
<filename>fr-FR.plg_extension_joomla.sys.ini</filename>
<filename>fr-FR.plg_finder_categories.ini</filename>
<filename>fr-FR.plg_finder_categories.sys.ini</filename>
<filename>fr-FR.plg_finder_contacts.ini</filename>
<filename>fr-FR.plg_finder_contacts.sys.ini</filename>
<filename>fr-FR.plg_finder_content.ini</filename>
<filename>fr-FR.plg_finder_content.sys.ini</filename>
<filename>fr-FR.plg_finder_newsfeeds.ini</filename>
<filename>fr-FR.plg_finder_newsfeeds.sys.ini</filename>
<filename>fr-FR.plg_finder_tags.ini</filename>
<filename>fr-FR.plg_finder_tags.sys.ini</filename>
<filename>fr-FR.plg_finder_weblinks.ini</filename>
<filename>fr-FR.plg_finder_weblinks.sys.ini</filename>
<filename>fr-FR.plg_installer_webinstaller.ini</filename>
<filename>fr-FR.plg_installer_webinstaller.sys.ini</filename>
<filename>fr-FR.plg_quickicon_extensionupdate.ini</filename>
<filename>fr-FR.plg_quickicon_extensionupdate.sys.ini</filename>
<filename>fr-FR.plg_quickicon_joomlaupdate.ini</filename>
<filename>fr-FR.plg_quickicon_joomlaupdate.sys.ini</filename>
<filename>fr-FR.plg_search_categories.ini</filename>
<filename>fr-FR.plg_search_categories.sys.ini</filename>
<filename>fr-FR.plg_search_contacts.ini</filename>
<filename>fr-FR.plg_search_contacts.sys.ini</filename>
<filename>fr-FR.plg_search_content.ini</filename>
<filename>fr-FR.plg_search_content.sys.ini</filename>
<filename>fr-FR.plg_search_newsfeeds.ini</filename>
<filename>fr-FR.plg_search_newsfeeds.sys.ini</filename>
<filename>fr-FR.plg_search_tags.ini</filename>
<filename>fr-FR.plg_search_tags.sys.ini</filename>
<filename>fr-FR.plg_search_weblinks.ini</filename>
<filename>fr-FR.plg_search_weblinks.sys.ini</filename>
<filename>fr-FR.plg_system_cache.ini</filename>
<filename>fr-FR.plg_system_cache.sys.ini</filename>
<filename>fr-FR.plg_system_debug.ini</filename>
<filename>fr-FR.plg_system_debug.sys.ini</filename>
<filename>fr-FR.plg_system_highlight.ini</filename>
<filename>fr-FR.plg_system_highlight.sys.ini</filename>
<filename>fr-FR.plg_system_languagecode.ini</filename>
<filename>fr-FR.plg_system_languagecode.sys.ini</filename>
<filename>fr-FR.plg_system_languagefilter.ini</filename>
<filename>fr-FR.plg_system_languagefilter.sys.ini</filename>
<filename>fr-FR.plg_system_log.ini</filename>
<filename>fr-FR.plg_system_log.sys.ini</filename>
<filename>fr-FR.plg_system_logout.ini</filename>
<filename>fr-FR.plg_system_logout.sys.ini</filename>
<filename>fr-FR.plg_system_p3p.ini</filename>
<filename>fr-FR.plg_system_p3p.sys.ini</filename>
<filename>fr-FR.plg_system_redirect.ini</filename>
<filename>fr-FR.plg_system_redirect.sys.ini</filename>
<filename>fr-FR.plg_system_remember.ini</filename>
<filename>fr-FR.plg_system_remember.sys.ini</filename>
<filename>fr-FR.plg_system_sef.ini</filename>
<filename>fr-FR.plg_system_sef.sys.ini</filename>
<filename>fr-FR.plg_twofactorauth_totp.ini</filename>
<filename>fr-FR.plg_twofactorauth_totp.sys.ini</filename>
<filename>fr-FR.plg_twofactorauth_yubikey.ini</filename>
<filename>fr-FR.plg_twofactorauth_yubikey.sys.ini</filename>
<filename>fr-FR.plg_user_contactcreator.ini</filename>
<filename>fr-FR.plg_user_contactcreator.sys.ini</filename>
<filename>fr-FR.plg_user_joomla.ini</filename>
<filename>fr-FR.plg_user_joomla.sys.ini</filename>
<filename>fr-FR.plg_user_profile.ini</filename>
<filename>fr-FR.plg_user_profile.sys.ini</filename>
<filename>fr-FR.tpl_hathor.ini</filename>
<filename>fr-FR.tpl_hathor.sys.ini</filename>
<filename>fr-FR.tpl_isis.ini</filename>
<filename>fr-FR.tpl_isis.sys.ini</filename>
<filename file="meta">install.xml</filename>
<filename file="meta">fr-FR.xml</filename>
</files>
<media destination="fr-FR"> 
<filename>index.html</filename>
<filename>js/index.html</filename>
<filename>js/calendar-setup.js</filename>
<filename>js/calendar.js</filename>
</media>
<params />
</extension>
</source>

<translate>

Notes:
* <code>fr-FR.lib_joomla.ini</code> : Add in both admin and site At least in site if "site only pack", see below
* <code>fr-FR.css</code> : NEW IN 1.7: this file can be added in the ADMINISTRATOR pack if one wants to change the fonts used to display the back-end interface.
* <code>fr-FR.xml</code> : Note the file="meta" tag, telling it's the basic xml holding info about the pack.
* <code>install.xml</code> : Mandatory! This file lets install/uninstall a language. Note file="meta"
* <code>fr-FR.localise.php</code> : Add in both admin and site. At least in site if "site only pack", see below
* Folder media <code>destination="fr-FR"</code> : If one needs to add a specific calendar
</translate>

<translate>
====All the ini files==== 
Beware of new formatting!
* Double quotes in the value should be written as "_QQ_" or as &quot;
</translate>

<translate>
====the fr-FR.xml==== 
</translate>

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metafile version="3.2" client="administrator">
<tag>fr-FR</tag>
<name>French (fr-FR)</name>
<version>3.4.1.1</version>
<creationDate>15/04/2013</creationDate>
<author>French translation team : joomla.fr</author>
<authorEmail>traduction@joomla.fr</authorEmail>
<authorUrl>www.joomla.fr</authorUrl>
<copyright>Copyright (C) 2005 - 2013 Open Source Matters & Joomla.fr. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<description>French administrator language for Joomla 3.0</description>
<metadata>
<name>Français (FR)</name>
<tag>fr-FR</tag>
<rtl>0</rtl>
<locale>fr_FR.utf8, fr_FR.UTF-8, fr_FR.UTF-8@euro, fr_FR, fre_FR, fr, france</locale>
<firstDay>1</firstDay>
<weekEnd>0,6</weekEnd>
</metadata>
<params />
</metafile>
</source>

<translate>

Notes:
* <locale> the locale is used to sort translated lists when present on the server.
* <firstDay>1</firstDay> used for the Calendar icon to specify what is the first day of the week in that language. 0 is Sunday, 1 is Monday, etc.
* <weekEnd>0,6</weekEnd> used for the Calendar, I defines the days of the week to be greyed. 0,6 is Saturday & Sunday, 1 would be Friday.
</translate>

<translate>
====the fr-FR.localise.php==== 
</translate>
<translate>

This file should be present at least in site zip


Explanation of this file: It replaces the <code>fr-FR.ignore.php</code> and it can be customized depending on languages.

*Ignore search words.


*Define upper and lower limit of search words length.


*Define number of characters to display for the result of the search.


*Define specific plural functionality for some languages where the value of the string can change depending on the count (Russian for example).


*Define custom transliteration (i.e. when NOT using the Unicode URLS parameter in Global Configuration) to ensure proper change of some alphabets to ascii for the alias used when SEF is on. (The transliteration which is now default in 1.7 should take care of all latin-based languages.)


*Define a custom calendar by adding a function as well as some js files


'''ALWAYS SAVE THIS FILE AS UTF8 NO BOM''' if it contains non-ascii glyphs (accented letters, etc.)
</translate>

<translate>
=====Example 1 - Custom transliteration NOT implemented===== 
Example of a basic <code>fr-FR.localise.php</code> (where custom transliteration is NOT implemented)
</translate>

<source lang="php"><?php
/**
* @version $Id: fr-FR.localise.php 15628 2010-03-27 05:20:29Z infograf768 $
* @copyright Copyright (C) 2005 - 2010 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

/**
* fr-FR localise class
*
* @package Joomla.Site
* @since 1.6
*/
abstract class Fr_FRLocalise { //// !!!! NOTE the use of Fr_FR for the class !!! // not the same as your language prefix.
/**
* Returns the potential suffixes for a specific number of items
*
* @param int $count The number of items.
* @return array An array of potential suffixes.
* @since 1.6
*/
public static function getPluralSuffixes($count) {
if ($count == 0) {
$return = array('0');
}
elseif($count == 1) {
$return = array('1');
}
else {
$return = array('MORE'); // Beware, this will be added to a language KEY. It should be in ascii and Uppercase.
}
return $return;
}
/**
* Returns the ignored search words
*
* @return array An array of ignored search words.
* @since 1.6
*/
public static function getIgnoredSearchWords() {
$search_ignore = array();
$search_ignore[] = "et";
$search_ignore[] = "si";
$search_ignore[] = "ou";
return $search_ignore;
}
/**
* Returns the lower length limit of search words
*
* @return integer The lower length limit of search words.
* @since 1.6
*/
public static function getLowerLimitSearchWord() {
return 3;
}
/**
* Returns the upper length limit of search words
*
* @return integer The upper length limit of search words.
* @since 1.6
*/
public static function getUpperLimitSearchWord() {
return 20;
}
/**
* Returns the number of chars to display when searching
*
* @return integer The number of chars to display when searching.
* @since 1.6
*/
public static function getSearchDisplayedCharactersNumber() {
return 200;
}
}</source>

<translate>
=====Example 2 - Custom transliteration implemented===== 


Example of the function to add to file <code>localise.php</code> when custom transliteration is desired
</translate>

<source lang="php">
/**
* This method processes a string and replaces all accented UTF-8 characters by unaccented
* ASCII-7 "equivalents"
*
* @param string $string The string to transliterate
* @return string The transliteration of the string
* @since 1.6
*/
public static function transliterate($string)
{
$str = JString::strtolower($string);

//Specific language transliteration.
//This one is for latin 1, latin supplement , extended A, Cyrillic, Greek

$glyph_array = array(
'a' => 'a,à,á,â,ã,ä,å,ā,ă,ą,ḁ,α,ά',
'ae' => 'æ',
'b' => 'β,б',
'c' => 'c,ç,ć,ĉ,ċ,č,ћ,ц',
'ch' => 'ч',
'd' => 'ď,đ,Ð,д,ђ,δ,ð',
'dz' => 'џ',
'e' => 'e,è,é,ê,ë,ē,ĕ,ė,ę,ě,э,ε,έ',
'f' => 'ƒ,ф',
'g' => 'ğ,ĝ,ğ,ġ,ģ,г,γ',
'h' => 'ĥ,ħ,Ħ,х',
'i' => 'i,ì,í,î,ï,ı,ĩ,ī,ĭ,į,и,й,ъ,ы,ь,η,ή',
'ij' => 'ĳ',
'j' => 'ĵ,j',
'ja' => 'я',
'ju' => 'яю',
'k' => 'ķ,ĸ,κ',
'l' => 'ĺ,ļ,ľ,ŀ,ł,л,λ',
'lj' => 'љ',
'm' => 'μ,м',
'n' => 'ñ,ņ,ň,ŉ,ŋ,н,ν',
'nj' => 'њ',
'o' => 'ò,ó,ô,õ,ø,ō,ŏ,ő,ο,ό,ω,ώ',
'oe' => 'œ,ö',
'p' => 'п,π',
'ph' => 'φ',
'ps' => 'ψ',
'r' => 'ŕ,ŗ,ř,р,ρ,σ,ς',
's' => 'ş,ś,ŝ,ş,š,с',
'ss' => 'ß,ſ',
'sh' => 'ш',
'shch' => 'щ',
't' => 'ţ,ť,ŧ,τ,т',
'th' => 'θ',
'u' => 'u,ù,ú,û,ü,ũ,ū,ŭ,ů,ű,ų,у',
'v' => 'в',
'w' => 'ŵ',
'x' => 'χ,ξ',
'y' => 'ý,þ,ÿ,ŷ',
'z' => 'ź,ż,ž,з,ж,ζ'
);

foreach( $glyph_array as $letter => $glyphs ) {
$glyphs = explode( ',', $glyphs );
$str = str_replace( $glyphs, $letter, $str );
}

return $str;
}
}
</source>

<translate>
=====Example 3 - Custom calendar implemented===== 
Here is an example of a function to add in the <code>localise.php</code> file in order to implement a custom calendar for fa-IR (Persian language)
</translate>

<source lang="php">
<?php
/**
* @version $Id: language.php 15628 2010-03-27 05:20:29Z infograf768 $
* @copyright Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.
* @copyright Copyright (C) 2005 - 2014 JoomlaFarsi.com. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

jimport('joomla.utilities.date');
abstract class Fa_IRLocalise {

public static function getPluralSuffixes($count) {
if ($count == 0)
{
$return = array('0');
}
elseif($count == 1)
{
$return = array('1');
}
else
{
$return = array('MORE');
}
return $return;
}

public static function getIgnoredSearchWords() {
$search_ignore = array();
$search_ignore[] = "and"; //change here to fit
$search_ignore[] = "in"; //change here to fit
$search_ignore[] = "on"; //change here to fit
return $search_ignore;
}

public static function getLowerLimitSearchWord() {
return 3;
}

public static function getUpperLimitSearchWord() {
return 20;
}

public static function getSearchDisplayedCharactersNumber() {
return 200;
}
}

class fa_IRDate extends JDate {
const DAY_NUMBER = "\x027\x03";
const DAY_NUMBER2 = "\x030\x03";
const DAY_YEAR = "\x032\x03";
const MONTH_ABBR = "\x033\x03";
const MONTH_NAME = "\x034\x03";
const MONTH_NUMBER = "\x035\x03";
const MONTH_NUMBER2 = "\x036\x03";
const MONTH_LENGTH = "\x037\x03";
const YEAR_ABBR = "\x040\x03";
const YEAR_NAME = "\x041\x03";
const AM_LOWER = "\x042\x03";
const AM_UPPER = "\x043\x03";
const PERSIAN_EPOCH = 1948320.5;

protected static $month_names = array("فروردين","ارديبهشت","خرداد","تیر","مرداد","شهریور","مهر","آبان","آذر","دی","بهمن","اسفند");

public function calendar($format, $local = false, $translate = true)
{
// Do string replacements for date format options that can be translated.
$format = preg_replace('/(^|[^\\\])d/', "\\1".self::DAY_NUMBER2, $format);
$format = preg_replace('/(^|[^\\\])j/', "\\1".self::DAY_NUMBER, $format);
$format = preg_replace('/(^|[^\\\])z/', "\\1".self::DAY_YEAR, $format);
$format = preg_replace('/(^|[^\\\])M/', "\\1".self::MONTH_ABBR, $format);
$format = preg_replace('/(^|[^\\\])F/', "\\1".self::MONTH_NAME, $format);
$format = preg_replace('/(^|[^\\\])n/', "\\1".self::MONTH_NUMBER, $format);
$format = preg_replace('/(^|[^\\\])m/', "\\1".self::MONTH_NUMBER2, $format);
$format = preg_replace('/(^|[^\\\])t/', "\\1".self::MONTH_LENGTH, $format);
$format = preg_replace('/(^|[^\\\])y/', "\\1".self::YEAR_ABBR, $format);
$format = preg_replace('/(^|[^\\\])Y/', "\\1".self::YEAR_NAME, $format);
$format = preg_replace('/(^|[^\\\])a/', "\\1".self::AM_LOWER, $format);
$format = preg_replace('/(^|[^\\\])A/', "\\1".self::AM_UPPER, $format);

// Format the date.
$return = parent::calendar($format, $local);

$jd = gregoriantojd($this->month, $this->day, $this->year);
$jalaliDate = self::jd_to_persian($jd);
$m = $jalaliDate['mon'];
$d = $jalaliDate['day'];
$y = $jalaliDate['year'];

// Manually modify the strings in the formated time.
if (strpos($return, self::DAY_NUMBER) !== false) {
$return = str_replace(self::DAY_NUMBER, $d , $return);
}
if (strpos($return, self::DAY_NUMBER2) !== false) {
$return = str_replace(self::DAY_NUMBER2, sprintf("%02d",$d), $return);
}
if (strpos($return, self::DAY_YEAR) !== false) {
$return = str_replace(self::DAY_YEAR, $jd - self::persian_to_jd(1,1,$y)+1, $return);
}
if (strpos($return, self::MONTH_ABBR) !== false) {
$return = str_replace(self::MONTH_ABBR, self::$month_names[$m-1] , $return);
}
if (strpos($return, self::MONTH_NAME) !== false) {
$return = str_replace(self::MONTH_NAME, self::$month_names[$m-1] , $return);
}
if (strpos($return, self::MONTH_NUMBER) !== false) {
$return = str_replace(self::MONTH_NUMBER, $m , $return);
}
if (strpos($return, self::MONTH_NUMBER2) !== false) {
$return = str_replace(self::MONTH_NUMBER2, sprintf("%02d", $m) , $return);
}
if (strpos($return, self::MONTH_LENGTH) !== false) {
$return = str_replace(self::MONTH_LENGTH, $m < 7 ? 31 : $m < 12 ? 30 : self::leap_persian($y) ? 30 : 29 , $return);
}
if (strpos($return, self::YEAR_ABBR) !== false) {
$return = str_replace(self::YEAR_ABBR, sprintf("%02d",$y % 100), $return);
}
if (strpos($return, self::YEAR_NAME) !== false) {
$return = str_replace(self::YEAR_NAME, $y, $return);
}
if (strpos($return, self::AM_LOWER) !== false) {
$return = str_replace(self::AM_LOWER, $this->format('a',$local)=='pm' ? 'ب ظ' : 'ق ظ', $return);
}
if (strpos($return, self::AM_UPPER) !== false) {
$return = str_replace(self::AM_UPPER, $this->format('a',$local)=='pm' ? 'ب ظ' : 'ق ظ', $return);
}

return $return;
}
public static function jd_to_persian($jd)

{

//var $year, $month, $day, $depoch, $cycle, $cyear, $ycycle,

// $aux1, $aux2, $yday;

$jd = floor($jd) + 0.5;

$depoch = $jd - self::persian_to_jd(1, 1, 475);

$cycle = floor($depoch / 1029983);

$cyear = $depoch % 1029983;

if ($cyear == 1029982) {

$ycycle = 2820;

} else {

$aux1 = floor($cyear / 366);

$aux2 = $cyear % 366;

$ycycle = floor(((2134 * $aux1) + (2816 * $aux2) + 2815) / 1028522) +

$aux1 + 1;

}

$year = $ycycle + (2820 * $cycle) + 474;

if ($year <= 0) {

$year--;

}

$yday = ($jd - self::persian_to_jd(1, 1, $year)) + 1;

$month = ($yday <= 186) ? ceil($yday / 31) : ceil(($yday - 6) / 30);

$day = ($jd - self::persian_to_jd($month, 1, $year)) + 1;

return array('year'=>$year, 'mon'=>$month,'day'=> $day);

}
public static function persian_to_jd($month, $day, $year)

{

//var $epbase, $epyear;

$epbase = $year - (($year >= 0) ? 474 : 473);

$epyear = 474 + $epbase % 2820;

return $day +

(($month <= 7) ?

(($month - 1) * 31) :

((($month - 1) * 30) + 6)

) +

floor((($epyear * 682) - 110) / 2816) +

($epyear - 1) * 365 +

floor($epbase / 2820) * 1029983 +

self::PERSIAN_EPOCH;

}

public static function leap_persian($year) {

return (((((($year - (($year > 0) ? 474 : 473)) % 2820) + 474) + 38) * 682) % 2816) < 682;

}

}

</source>

<translate>

Note: One has also to add the right <code>calendar.js</code> files in the package.
</translate>

<translate>
==The Site-only pack== 


'''Concerning those of you providing "site only" packs:'''


I.e. IT IS NECESSARY TO PROVIDE AN ADMIN PACK WITH ALL FILES, SOME OF THEM SHOULD BE TRANSLATED and to post a unique package as for a real "full" pack (See above).


Why? ==> because some plugin ini files are used in front-end! Here is a typical administrator <code>install.xml</code> in this case. Example for 3.3.x, the files to translate are indicated by =======> :
</translate>

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="3.3" client="administrator" type="language" method="upgrade">
<name>MyLanguage (xx-XX)</name>
<tag>xx-XX</tag>
<version>3.3.3.1</version>
<creationDate>July 2014</creationDate>
<author>MyLanguage translation team : xx-XX Team/author</author>
<authorEmail>traduction@mysite.com</authorEmail>
<authorUrl>http://mysite.com</authorUrl>
<copyright>Copyright (C) 2005 - 2014 Open Source Matters. All rights reserved.</copyright>
<copyright>Copyright (C) date_year - date_year My Team or name. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<description>xx-XX administrator language for 3.3.x</description>
<files>
<filename>xx-XX.com_admin.ini</filename>
<filename>xx-XX.com_admin.sys.ini</filename>
<filename>xx-XX.com_banners.ini</filename>
<filename>xx-XX.com_banners.sys.ini</filename>
<filename>xx-XX.com_ajax.ini</filename>
<filename>xx-XX.com_ajax.sys.ini</filename>
<filename>xx-XX.com_cache.ini</filename>
<filename>xx-XX.com_cache.sys.ini</filename>
<filename>xx-XX.com_categories.ini</filename>
<filename>xx-XX.com_categories.sys.ini</filename>
<filename>xx-XX.com_checkin.ini</filename>
<filename>xx-XX.com_checkin.sys.ini</filename>
<filename>xx-XX.com_config.ini</filename>
<filename>xx-XX.com_config.sys.ini</filename>
<filename>xx-XX.com_contact.ini</filename>
<filename>xx-XX.com_contact.sys.ini</filename>
<filename>xx-XX.com_content.ini</filename>
<filename>xx-XX.com_content.sys.ini</filename>
<filename>xx-XX.com_contenthistory.ini</filename>
<filename>xx-XX.com_contenthistory.sys.ini</filename>
<filename>xx-XX.com_cpanel.ini</filename>
<filename>xx-XX.com_cpanel.sys.ini</filename>
<filename>xx-XX.com_finder.ini</filename>
<filename>xx-XX.com_finder.sys.ini</filename>
<filename>xx-XX.com_installer.ini</filename>
<filename>xx-XX.com_installer.sys.ini</filename>
<filename>xx-XX.com_joomlaupdate.ini</filename>
<filename>xx-XX.com_joomlaupdate.sys.ini</filename>
<filename>xx-XX.com_languages.ini</filename>
<filename>xx-XX.com_languages.sys.ini</filename>
<filename>xx-XX.com_login.ini</filename>
<filename>xx-XX.com_login.sys.ini</filename>
<filename>xx-XX.com_mailto.sys.ini</filename>
<filename>xx-XX.com_media.ini</filename>
<filename>xx-XX.com_media.sys.ini</filename>
<filename>xx-XX.com_menus.ini</filename>
<filename>xx-XX.com_menus.sys.ini</filename>
<filename>xx-XX.com_messages.ini</filename>
<filename>xx-XX.com_messages.sys.ini</filename>
<filename>xx-XX.com_modules.ini</filename>
<filename>xx-XX.com_modules.sys.ini</filename>
<filename>xx-XX.com_newsfeeds.ini</filename>
<filename>xx-XX.com_newsfeeds.sys.ini</filename>
<filename>xx-XX.com_plugins.ini</filename>
<filename>xx-XX.com_plugins.sys.ini</filename>
<filename>xx-XX.com_postinstall.ini</filename>
<filename>xx-XX.com_postinstall.sys.ini</filename>
<filename>xx-XX.com_redirect.ini</filename>
<filename>xx-XX.com_redirect.sys.ini</filename>
<filename>xx-XX.com_search.ini</filename>
<filename>xx-XX.com_search.sys.ini</filename>
<filename>xx-XX.com_tags.ini</filename>
<filename>xx-XX.com_tags.sys.ini</filename>
<filename>xx-XX.com_templates.ini</filename>
<filename>xx-XX.com_templates.sys.ini</filename>
<filename>xx-XX.com_users.ini</filename>
<filename>xx-XX.com_users.sys.ini</filename>
<filename>xx-XX.com_weblinks.ini</filename>
<filename>xx-XX.com_weblinks.sys.ini</filename>
<filename>xx-XX.com_wrapper.ini</filename>
<filename>xx-XX.com_wrapper.sys.ini</filename>
<filename>xx-XX.ini</filename>
<filename>xx-XX.lib_joomla.ini</filename>
<filename>xx-XX.localise.php</filename>
<filename>xx-XX.mod_custom.ini</filename>
<filename>xx-XX.mod_custom.sys.ini</filename>
<filename>xx-XX.mod_feed.ini</filename>
<filename>xx-XX.mod_feed.sys.ini</filename>
<filename>xx-XX.mod_latest.ini</filename>
<filename>xx-XX.mod_latest.sys.ini</filename>
<filename>xx-XX.mod_logged.ini</filename>
<filename>xx-XX.mod_logged.sys.ini</filename>
<filename>xx-XX.mod_login.ini</filename>
<filename>xx-XX.mod_login.sys.ini</filename>
<filename>xx-XX.mod_menu.ini</filename>
<filename>xx-XX.mod_menu.sys.ini</filename>
<filename>xx-XX.mod_multilangstatus.ini</filename>
<filename>xx-XX.mod_multilangstatus.sys.ini</filename>
<filename>xx-XX.mod_popular.ini</filename>
<filename>xx-XX.mod_popular.sys.ini</filename>
<filename>xx-XX.mod_quickicon.ini</filename>
<filename>xx-XX.mod_quickicon.sys.ini</filename>
<filename>xx-XX.mod_stats_admin.ini</filename>
<filename>xx-XX.mod_stats_admin.sys.ini</filename>
<filename>xx-XX.mod_status.ini</filename>
<filename>xx-XX.mod_status.sys.ini</filename>
<filename>xx-XX.mod_submenu.ini</filename>
<filename>xx-XX.mod_submenu.sys.ini</filename>
<filename>xx-XX.mod_title.ini</filename>
<filename>xx-XX.mod_title.sys.ini</filename>
<filename>xx-XX.mod_toolbar.ini</filename>
<filename>xx-XX.mod_toolbar.sys.ini</filename>
<filename>xx-XX.mod_version.ini</filename>
<filename>xx-XX.mod_version.sys.ini</filename>
<filename>xx-XX.plg_authentication_cookie.ini</filename>
<filename>xx-XX.plg_authentication_cookie.sys.ini</filename>
<filename>xx-XX.plg_authentication_gmail.ini</filename>
<filename>xx-XX.plg_authentication_gmail.sys.ini</filename>
<filename>xx-XX.plg_authentication_joomla.ini</filename>
<filename>xx-XX.plg_authentication_joomla.sys.ini</filename>
<filename>xx-XX.plg_authentication_ldap.ini</filename>
<filename>xx-XX.plg_authentication_ldap.sys.ini</filename>
=========> <filename>xx-XX.plg_captcha_recaptcha.ini</filename>
<filename>xx-XX.plg_captcha_recaptcha.sys.ini</filename>
<filename>xx-XX.plg_content_emailcloak.ini</filename>
<filename>xx-XX.plg_content_contact.ini</filename>
<filename>xx-XX.plg_content_contact.sys.ini</filename>
<filename>xx-XX.plg_content_emailcloak.sys.ini</filename>
<filename>xx-XX.plg_content_finder.ini</filename>
<filename>xx-XX.plg_content_finder.sys.ini</filename>
<filename>xx-XX.plg_content_joomla.ini</filename>
<filename>xx-XX.plg_content_joomla.sys.ini</filename>
<filename>xx-XX.plg_content_loadmodule.ini</filename>
<filename>xx-XX.plg_content_loadmodule.sys.ini</filename>
=========> <filename>xx-XX.plg_content_pagebreak.ini</filename>
<filename>xx-XX.plg_content_pagebreak.sys.ini</filename>
<filename>xx-XX.plg_content_pagenavigation.ini</filename>
<filename>xx-XX.plg_content_pagenavigation.sys.ini</filename>
=========> <filename>xx-XX.plg_content_vote.ini</filename>
<filename>xx-XX.plg_content_vote.sys.ini</filename>
<filename>xx-XX.plg_editors_codemirror.ini</filename>
<filename>xx-XX.plg_editors_codemirror.sys.ini</filename>
<filename>xx-XX.plg_editors_none.ini</filename>
<filename>xx-XX.plg_editors_none.sys.ini</filename>
<filename>xx-XX.plg_editors_tinymce.ini</filename>
<filename>xx-XX.plg_editors_tinymce.sys.ini</filename>
=========> <filename>xx-XX.plg_editors-xtd_article.ini</filename>
<filename>xx-XX.plg_editors-xtd_article.sys.ini</filename>
=========> <filename>xx-XX.plg_editors-xtd_image.ini</filename>
<filename>xx-XX.plg_editors-xtd_image.sys.ini</filename>
=========> <filename>xx-XX.plg_editors-xtd_pagebreak.ini</filename>
<filename>xx-XX.plg_editors-xtd_pagebreak.sys.ini</filename>
=========> <filename>xx-XX.plg_editors-xtd_readmore.ini</filename>
<filename>xx-XX.plg_editors-xtd_readmore.sys.ini</filename>
<filename>xx-XX.plg_extension_joomla.ini</filename>
<filename>xx-XX.plg_extension_joomla.sys.ini</filename>
=========> <filename>xx-XX.plg_finder_categories.ini</filename>
<filename>xx-XX.plg_finder_categories.sys.ini</filename>
=========> <filename>xx-XX.plg_finder_contacts.ini</filename>
<filename>xx-XX.plg_finder_contacts.sys.ini</filename>
=========> <filename>xx-XX.plg_finder_content.ini</filename>
<filename>xx-XX.plg_finder_content.sys.ini</filename>
=========> <filename>xx-XX.plg_finder_newsfeeds.ini</filename>
<filename>xx-XX.plg_finder_newsfeeds.sys.ini</filename>
=========> <filename>xx-XX.plg_finder_tags.ini</filename>
<filename>xx-XX.plg_finder_tags.sys.ini</filename>
=========> <filename>xx-XX.plg_finder_weblinks.ini</filename>
<filename>xx-XX.plg_finder_weblinks.sys.ini</filename>
<filename>xx-XX.plg_installer_webinstaller.ini</filename>
<filename>xx-XX.plg_installer_webinstaller.sys.ini</filename>
<filename>xx-XX.plg_quickicon_extensionupdate.ini</filename>
<filename>xx-XX.plg_quickicon_extensionupdate.sys.ini</filename>
<filename>xx-XX.plg_quickicon_joomlaupdate.ini</filename>
<filename>xx-XX.plg_quickicon_joomlaupdate.sys.ini</filename>
=========> <filename>xx-XX.plg_search_categories.ini</filename>
<filename>xx-XX.plg_search_categories.sys.ini</filename>
=========> <filename>xx-XX.plg_search_contacts.ini</filename>
<filename>xx-XX.plg_search_contacts.sys.ini</filename>
=========> <filename>xx-XX.plg_search_content.ini</filename>
<filename>xx-XX.plg_search_content.sys.ini</filename>
=========> <filename>xx-XX.plg_search_newsfeeds.ini</filename>
<filename>xx-XX.plg_search_newsfeeds.sys.ini</filename>
=========> <filename>xx-XX.plg_search_tags.ini</filename>
<filename>xx-XX.plg_search_tags.sys.ini</filename>
=========> <filename>xx-XX.plg_search_weblinks.ini</filename>
<filename>xx-XX.plg_search_weblinks.sys.ini</filename>
<filename>xx-XX.plg_system_cache.ini</filename>
<filename>xx-XX.plg_system_cache.sys.ini</filename>
<filename>xx-XX.plg_system_debug.ini</filename>
<filename>xx-XX.plg_system_debug.sys.ini</filename>
<filename>xx-XX.plg_system_highlight.ini</filename>
<filename>xx-XX.plg_system_highlight.sys.ini</filename>
<filename>xx-XX.plg_system_languagecode.ini</filename>
<filename>xx-XX.plg_system_languagecode.sys.ini</filename>
<filename>xx-XX.plg_system_languagefilter.ini</filename>
<filename>xx-XX.plg_system_languagefilter.sys.ini</filename>
<filename>xx-XX.plg_system_log.ini</filename>
<filename>xx-XX.plg_system_log.sys.ini</filename>
<filename>xx-XX.plg_system_logout.ini</filename>
<filename>xx-XX.plg_system_logout.sys.ini</filename>
<filename>xx-XX.plg_system_p3p.ini</filename>
<filename>xx-XX.plg_system_p3p.sys.ini</filename>
<filename>xx-XX.plg_system_redirect.ini</filename>
<filename>xx-XX.plg_system_redirect.sys.ini</filename>
<filename>xx-XX.plg_system_remember.ini</filename>
<filename>xx-XX.plg_system_remember.sys.ini</filename>
<filename>xx-XX.plg_system_sef.ini</filename>
<filename>xx-XX.plg_system_sef.sys.ini</filename>
<filename>xx-XX.plg_twofactorauth_totp.ini</filename>
<filename>xx-XX.plg_twofactorauth_totp.sys.ini</filename>
<filename>xx-XX.plg_twofactorauth_yubikey.ini</filename>
<filename>xx-XX.plg_twofactorauth_yubikey.sys.ini</filename>
<filename>xx-XX.plg_user_contactcreator.ini</filename>
<filename>xx-XX.plg_user_contactcreator.sys.ini</filename>
<filename>xx-XX.plg_user_joomla.ini</filename>
<filename>xx-XX.plg_user_joomla.sys.ini</filename>
=========> <filename>xx-XX.plg_user_profile.ini</filename>
<filename>xx-XX.plg_user_profile.sys.ini</filename>
<filename>xx-XX.tpl_hathor.ini</filename>
<filename>xx-XX.tpl_hathor.sys.ini</filename>
<filename>xx-XX.tpl_isis.ini</filename>
<filename>xx-XX.tpl_isis.sys.ini</filename>
=========> <filename file="meta">install.xml</filename>
=========> <filename file="meta">xx-XX.xml</filename>
</files>
<params />
</extension>

</source>

<translate>

For the unstranslated files, just copy the <code>en-GB</code> ones and change the language prefix.
</translate>

<translate>
==What not to translate== 
Don't translate these lines:

* file <code>fr-FR.ini</code> = the lines for <code>"JHELP_COMPONENTS_"</code>

example:
</translate>
<source lang="php">
JHELP_COMPONENTS_MESSAGING_INBOX="Components_Messaging_Inbox"
</source>

<translate>

They are used for mapping the help. When a specific wiki for help per language is available, they will be functional.
</translate>

==Frequent Asked Questions==
===Why we use .ini files instead of .po .mo===
INI files were choosen in 2006 for several reasons:

* There was no specific app to deal with .po on all platforms (Poedit was not available on Windows)
* Anyone, even without any code knowledge, could create/edit an ini file
* ini files are readable while .po are not
* You can't load more than one .pot file per page.

but not only, and this is why it is better to go on:

the following is an example picked from Wordpress of the code in a simple .php file (BTW WP does NOT use any plurals, as I could see in their .po files):

<source lang="php">
get_current_screen()->add_help_tab( array(
'id' => 'publish-box',
'title' => __('Publish Settings'),
'content' => $publish_box,
) );

$discussion_settings = '<p>' . __('<strong>Send Trackbacks</strong> - Trackbacks are a way to notify legacy blog systems that you’ve linked to them. Enter the URL(s) you want to send trackbacks. If you link to other WordPress sites they’ll be notified automatically using pingbacks, and this field is unnecessary.') . '</p>';
$discussion_settings .= '<p>' . __('<strong>Discussion</strong> - You can turn comments and pings on or off, and if there are comments on the post, you can see them here and moderate them.') . '</p>';

get_current_screen()->add_help_tab( array(
'id' => 'discussion-settings',
'title' => __('Discussion Settings'),
'content' => $discussion_settings,
) );
} elseif ( 'page' == $post_type ) {
$page_attributes = '<p>' . __('<strong>Parent</strong> - You can arrange your pages in hierarchies. For example, you could have an “About” page that has “Life Story” and “My Dog” pages under it. There are no limits to how many levels you can nest pages.') . '</p>' .
'<p>' . __('<strong>Template</strong> - Some themes have custom templates you can use for certain pages that might have additional features or custom layouts. If so, you’ll see them in this dropdown menu.') . '</p>' .
'<p>' . __('<strong>Order</strong> - Pages are usually ordered alphabetically, but you can choose your own order by entering a number (1 for first, etc.) in this field.') . '</p>';

get_current_screen()->add_help_tab( array(
'id' => 'page-attributes',
'title' => __('Page Attributes'),
'content' => $page_attributes,
) );
}
</source>

This for GetText:

<source lang="php">
__('<strong>Parent</strong> - You can arrange your pages in hierarchies. For example, you could have an “About” page that has “Life Story” and “My Dog” pages under it. There are no limits to how many levels you can nest pages.')
</source>

It is simpler with ini files:

<source lang="php">
JText::_("SOME_CONSTANT")
</source>

===Working with plurals===
Some languages like Russian do NOT have the same plurals as English. They need to add strins to fit their definitions. Joomla CMS provides a solution for it and it can be seen in the file localise.php added to the language package. For example:

Concerning plurals, this is the Russian plural:

<source lang="php">
public static function getPluralSuffixes($count)
{
if ($count == 0) {
$return = array('0');
} else {
$return = array(($count%10==1 && $count%100!=11 ? '1' : ($count%10>=2 && $count%10<=4 && ($count%100<10 || $count%100>=20) ? '2' : 'MORE')));
}
return $return;
}
</source>

An this is the Scottish gaelic one
<source lang="php">
public static function getPluralSuffixes($count) {
if ($count == 0 || $count > 19) {
$return = array('0');
}
elseif($count == 1 || $count == 11) {
$return = array('1');
}
elseif($count == 2 || $count == 12) {
$return = array('2');
}
elseif(($count > 2 && $count < 12) || ($count > 12 && $count < 19)) {
$return = array('FEW');
}
return $return;
}
</source>

Now compare with en-GB:

<source lang="php">
public static function getPluralSuffixes($count) {
if ($count == 0) {
$return = array('0');
}
elseif($count == 1) {
$return = array('1');
}
else {
$return = array('MORE');
}
return $return;
}
</source>

This means that when we have in en-GB:

<source lang="php">
COM_BANNERS_BANNERS_N_ITEMS_CHECKED_IN_0="No banner successfully checked in"
COM_BANNERS_BANNERS_N_ITEMS_CHECKED_IN_1="%d banner successfully checked in"
COM_BANNERS_BANNERS_N_ITEMS_CHECKED_IN_MORE="%d banners successfully checked in"
</source>

In Russian they need:

<source lang="php">
COM_BANNERS_BANNERS_N_ITEMS_CHECKED_IN_0="Ни один баннер не был разблокирован"
COM_BANNERS_BANNERS_N_ITEMS_CHECKED_IN_1="%d баннер успешно разблокирован"
COM_BANNERS_BANNERS_N_ITEMS_CHECKED_IN_2="%d баннера успешно разблокировано"
COM_BANNERS_BANNERS_N_ITEMS_CHECKED_IN_MORE="%d баннеров успешно разблокировано"
</source>

===Standard ISO codes for naming language packages===
The official link concerning Country codes is: https://www.iso.org/obp/ui/#search

Joomla uses alpha-2 codes:

CS was the official country code of Tchecoslovakia BEFORE it was separated into the Czeck Republic (CZ) and Slovakia(SK)

Our Lang tags are composed of 2 parts:

* the languagecode
* the countrycode

Here is the official list for language code: http://www.iso.org/iso/home/standards/language_codes.htm

When possible we use the 2 letters language code, otherwise we use 3. For example we have for Joomla

ckb-IQ for Kurdish Sorani

srp-ME for Montenegrin

<translate>

[[Category:Joomla! 3.0]]
[[Category:Tutorials]]
[[Category:Language Development]]
</translate>

User talk:Javiparati

2015-07-13T08:33:46Z

Javiparati: /* Translation Tags. */

== Translation Tags. ==

Bonjour Javier,<br />
I hope everything goes well for you.<br />

The thing with tagging for translation is that the # for the section is generated automaticly then in fact (I think this is what you did with your text the right way) you just need to add the tags <nowiki><translate>Text to translate</translate></nowiki>. Here, the <nowiki></nowiki> will/has been generated by the system.<br />
But, at this point, if there's no prob for you, I'd prefer to tag/mark for translation myself for the proper management of my workflow.<br />
Just add your changes on the page then I will be notified + usually I tag/mark/translate (in FR ;) ) the same day max.<br /><br />

If you want a '''new''' page to be translated, please follw: <br />
https://docs.joomla.org/Category:Needs_to_be_marked_for_translation<br />
<br />
Thanks for your help,<br />
([[User:MATsxm|MATsxm]] ([[User talk:MATsxm|talk]]) 08:59, 12 July 2015 (CDT))

:Hi Javier

:I added back in the new "test" @[[User:MATsxm|MATsxm]] explained it well. Just worry about the content though, not the tags. You can add them in, but MAT will know if the page's content changes and can add the tags. Anything with a  is added by the system when the content changes are approved.

::[[User:Tom Hutchison|Tom Hutchison]] ([[User talk:Tom Hutchison|talk]]) 11:31, 12 July 2015 (CDT)

Ok. Thanks ^_^

[[User:Javiparati|Javier Gómez]] ([[User talk:Javiparati|talk]]) 03:33, 13 July 2015 (CDT)

Joomla:Commit Guidelines

2015-07-12T11:48:01Z

Javiparati: Tom have I setted well the Tranlsation tag?

<noinclude><languages /></noinclude>
<translate>
Commit Guidelines for the Joomla! CMS.


These guidelines are not meant to be strict rules, but a guide for what we consider best practice.</translate>
<translate>== Merge-Commit vs Squashing == </translate>

<translate>=== Merge-Commit === 
When you click the “Merge” button on GitHub, it will create a merge-commit named “Merge pull request #1234 from User/Branch”. This commit will show together with all commits in the PR in the log. Each commit will have the original date when it was created, not when it was actually merged. While this is nice to preserve the actual commit history and is fine with Git Clients which show the branches, it becomes unreadable especially on the GitHub log page.</translate>

<translate>=== Squashing === </translate>

<translate>
When you squash the commits, you create a single commit consisting of all original commits. This single commit is then pushed to master and can be named in a standardised way.</translate>

<translate>=== Recommendation === </translate>

<translate>
We recommend to squash the commits in most cases. The “Merge” button in GitHub should only be used for simple PRs with only a few commits and when it’s only a few days old. Most of time, this is the case for simple PRs dealing with codestyle or language strings.</translate>

<translate>== Naming Conventions == 
When squashing commits, one should follow these naming conventions so the log will become easier to read.</translate>

<translate>=== Format === </translate>

:'''<[Prefix]> <Title>. <Issue>'''
:<''Description''>

<translate>=== Prefixes === </translate>

{| class="wikitable"
!<translate>
Prefix</translate>
!<translate>
Meaning</translate>
|-
|sec
|<translate>
Security</translate>
|-
|bug
|<translate>
Bug fix</translate>
|-
|add
|<translate>
Add</translate>
|-
|rem
|<translate>
Remove</translate>
|-
|lang
|Language
|-
|doc
|<translate>
Documentation / Notes</translate>
|-
|imp
|<translate>
Improvement</translate>
|-
|tests
|<translate>
Tests</translate>
|}

<translate>
A commit may have multiple prefixes. If that’s the case, each goes into its own brackets.</translate>

<translate>=== Title === </translate>

<translate>
Use a descriptive title for the commit. Usually the title of the PR will be fine.</translate>

<translate>=== Issue === </translate>
<translate>
After the title we add a dot, followed by a text like “Closes #1234”. This will automatically close the PR when the commit is pushed to staging and also provides a link to the PR. See https://help.github.com/articles/closing-issues-via-commit-messages for the available keywords.</translate>

<translate>=== Description === </translate>

<translate>
The description is optional. It can contain additional information to the commit. Usually that is not needed as the information is available in the linked Pull Request.</translate>

<translate>=== Example === </translate>

:[lng] Clarify content smart search plugins. Closes #1833

<noinclude>
<translate>

[[Category:CMS Development Reference]]
[[Category:CMS Maintainers]]
[[Category:Guidelines]]
</translate>
</noinclude>

Testing Joomla Extensions with Codeception

2015-06-04T07:44:08Z

Javiparati: /* What is Codeception? */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

=== Types of tests ===
Codeception provides possibilities to do Unit Testing or to Test APIs, however '''this page is focused in System Testing'''.

- '''System testing''' uses a production-like environment to verify the system as a whole, including user interfaces, databases, web servers, logging, etc.

- A '''unit test''' verifies a single behavior of a single unit – this can be a function, a method, or a class. A logical unit is something that can be reasoned about in isolation. The unit must be completely under your control. The test should limit the number of other units it touches on, and should not touch any part outside of your own system. As such, the test should only fail for one reason.

- '''Integration testing''' means we’re verifying that that different units are working together. It focuses on the interfaces between components. Some of these components may be from third parties. When they break, they signal that, although individual units may behave correctly, something changed in the API that caused failure in another place. Often, integration tests are slower than unit tests.

As mentioned at the beginning of this text, the current page is focused on '''System Tests''' and more specifically using Webdriver. The reason is that we came to the conclusion that this type of tests combined with the already existing Unit tests in Joomla are the most successful way to test our current code.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.
[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','30',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 30 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

A waitForText over 10 seconds will definitely mean that something is not performing well. Maybe a non strict Locator is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

Testing Joomla Extensions with Codeception

2015-06-03T11:05:33Z

Javiparati: fix typo

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

Codeception provides possibilities to do Unit Testing or to Test APIs, however this page is focused in '''System Testing'''.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.
[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','30',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 30 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

A waitForText over 10 seconds will definitely mean that something is not performing well. Maybe a non strict Locator is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Complex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

Testing Joomla Extensions with Codeception

2015-06-03T11:03:08Z

Javiparati: /* How much time should I wait for an Element or Text? */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

Codeception provides possibilities to do Unit Testing or to Test APIs, however this page is focused in '''System Testing'''.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.
[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for','30',['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. '''We suggest to set it for 30 seconds''', because running the tests in slow computers can easily get to that time in some tasks.

A waitForText over 10 seconds will definitely mean that something is not performing well. Maybe a non strict Locator is being used and Selenium takes to much time to find the element. However we have even identified cases were some steps take longer than 30 seconds in very slow computers, specifically installing joomla, see https://github.com/joomla-projects/joomla-browser/commit/b70f195140e599649cf98f051d7a31388c4f1632. For this cases we can't do much, other than recommend to add more memory to the local web server.

=== Quote and Double Quotes in Compex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

Testing Joomla Extensions with Codeception

2015-05-31T12:33:29Z

Javiparati: /* Getting started from scratch: what you need to download and install */

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

Codeception provides possibilities to do Unit Testing or to Test APIs, however this page is focused in '''System Testing'''.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Important note:''' no matter if you are executing [https://github.com/joomla/joomla-cms/tree/staging/tests/codeception#testing-joomla-cms Joomla CMS Tests], [https://github.com/joomla-extensions/weblinks#tests Weblinks], or tests in other Joomla extensions, in any case you are asked to fork the repository into your local machine under your htdocs folder of your local web-server. The reason is that, the automated scripts that launches the tests use the repository files for the tests.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with setting up a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.
[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for', 10, ['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. We suggest to set it for 10 seconds. A waitForText over 10 seconds will definitely mean that something is not performing well.

=== Quote and Double Quotes in Compex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

Testing Joomla Extensions with Codeception

2015-05-31T12:27:18Z

Javiparati: remove the need for wget since is not anymore needed

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

Codeception provides possibilities to do Unit Testing or to Test APIs, however this page is focused in '''System Testing'''.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Very important:''' The downloaded GIT directory must be inside your htdocs folder of your local web-server. Otherwise the test will not work! The files from the 'weblinks' folder must be loadable via your local web-server with your browser.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with a local web-server, learn that first before you advance futher.

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.
[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for', 10, ['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. We suggest to set it for 10 seconds. A waitForText over 10 seconds will definitely mean that something is not performing well.

=== Quote and Double Quotes in Compex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

Testing Joomla Extensions with Codeception

2015-05-31T12:26:49Z

Javiparati: remove the need for Wget

<nowiki>Note: this page is under construction</nowiki>

== What is Codeception? ==
Codeception PHP Testing Framework is designed to work just out of the box. This means its installation requires minimal steps and no external dependencies preinstalled (except PHP, of course). Only one configuration step should be taken and you are ready to test your web application from an eye of actual user.

See the following video of codeception in action testing Joomla:

{{#widget:YouTube|id=Vc1BJNnhsFM}}

Codeception provides possibilities to do Unit Testing or to Test APIs, however this page is focused in '''System Testing'''.

== Why Use Codeception? ==
''Why use Codeception when we already have Selenium IDE?''

Codeception works great with Selenium. But with Codeception you can write your tests in PHP. The main reason is: Selenium IDE tests are tightly bound to XPath locators. If you ever change anything in layout tests will fall. Codeception locators are more stable. You can use names, labels, button names and CSS to match elements on page.

'''Features'''
* Selenium WebDriver integration
* Elements matched by name, CSS, XPath
* PageObjects and StepObjects included
* Powered by PHPUnit
* Data Cleanup
* Parallel Execution of tests
* BDD-style readable tests

== Architecture of a test ==
The testing framework is built on the three layered testing architecture

=== Scenarios (Cept Class) ===
Cept or Test, it is the main class which contains steps of execution for the tests, Cept Class will call Step Class functions which will indirectly make use of page objects to perform operations

Example:
<source lang="php">
$I = new AcceptanceTester($scenario);
$I->wantTo('Install Joomla CMS');
$I->amOnPage('http://localhost/installation/index.php');
// I Wait for the text Main Configuration, meaning that the page is loaded
$I->waitForText('Main Configuration', 10, 'h3');
$I->click(JoomlaInstallationConfigurationPage::$elements['Language Selector']);
$I->click(JoomlaInstallationConfigurationPage::$elements['English (United Kingdom)']);
$I->fillField('Site Name', 'weblinks');
$I->fillField('Description', 'Site for testing Weblinks component');
$I->fillField('Admin Email', $cfg['Admin email']);
$I->fillField('Admin Username', $cfg['username']);
$I->fillField('Admin Password', $cfg['password']);
$I->fillField('Confirm Admin Password', $cfg['password']);
$I->click('Next');
...
</source>

=== Page Objects ===
Each page on your application has a class which we call page objects, each page class will have information about the URL, fields, Text present on the page. We use the best possible selector for any field on the page.

==== Example ====
<source lang="php">
class JoomlaAdministratorLoginManagerPage
{
/**
* @var string Url of the page
*/
public static $URL = '/administrator/index.php';

/**
* Array of Page elements indexed by descriptive name or label
*
* @var array
*/
public static $elements = array(
'username' => "#mod-login-username",
'password' => "#mod-login-password"
);
}
</source>

==== Naming convention for Page Objects ====
When this document is created Codeception 2.0 was not having a PSR-4 compatible autoloader. Therefore we are creating a convention so with the future Codeception 2.1 with PSR-4 compatible autoloader (https://github.com/Codeception/Codeception/pull/1228) we are creating a naming convention for Pages so it will cost us a small effort to move to autoloaded classes in the future.

The naming convention works as follows:

APPLICATION (for example Joomla, Patchtester, Weblinks or your Extension name)
+ CLIENT (in Joomla we use it for defining if is Installation, Administrator or Frontend
+ CLIENT PART (In Joomla we use it following the menu are were it belongs: Components, Menus, System,...)
+ PAGE NAME (The Page name)
+ Page

Examples:

JoomlaAdministratorLoginPage
JoomlaAdministratorSystemGlobalconfigurationPage
JoomlaInstallationConfigurationPage

And they are located with a folder estructure similar to:

[[File:System_tests_pages_folder_structure.png|framed|center|Folder estructure for Pages in System Tests]]

Remind that in Codeception 2.0 you need to specify each folder in the acceptance/_bootstrap.php file:
<source lang="php">
<?php
// Here you can initialize variables that will be available to your tests
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/installation');
\Codeception\Util\Autoload::registerSuffix('Page', __DIR__.DIRECTORY_SEPARATOR.'_pages/joomla/administrator');
</source>

==== Documentation ====
More info: http://codeception.com/docs/07-AdvancedUsage#PageObjects

=== Step Objects ===
Step Objects are classes which contains steps which are to be executed on the application to perform certain operations, step objects make use of page objects to perform these actions.

Example:
<source lang="php">
class JoomlaAdministratorLoginSteps extends \AcceptanceTester
{
/**
* Function to execute an Admin Login for Joomla 3
*
* @return void
*/
public function doAdministratorLogin($user, $password)
{
$I = $this;
$I->amOnPage(\JoomlaAdministratorLoginPage::$URL);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['username'], $user);
$I->fillField(\JoomlaAdministratorLoginPage::$elements['password'], $password);
$I->click('Log in');
$I->see('Category Manager');
}
}
</source>

More info: http://codeception.com/docs/07-AdvancedUsage#StepObjects

=== The Joomla Browser Module ===
The Joomla Browser is a Codeception Module that incorporates general functions to your tests like:
- do administrator login
- install joomla
- install extension
- ...

Find details about it at: https://github.com/joomla-projects/joomla-browser#table-of-contents

== Getting started from scratch: what you need to download and install ==
To get the test environment running you need to have several components installed.

'''Very important:''' The downloaded GIT directory must be inside your htdocs folder of your local web-server. Otherwise the test will not work! The files from the 'weblinks' folder must be loadable via your local web-server with your browser.

=== local webserver ===
If you do not already have a local test server running you may want to check out:
https://www.mamp.info/
https://www.apachefriends.org/
http://www.ampps.com/

If you are not familiar with a local web-server, learn that first before you advance futher.

====Wget on Mac====
For Mac Users Homebrew (package manager for OS X) is a very easy way to get wget running. Download Homebrew at: http://brew.sh/
After installation run the following command in your terminal

<source lang="php">
brew install wget
</source>

=== Java Runtime Environment (JRE) ===
The JRE has to be installed, so the tests will be executable. You find the recent versions at the Oracle Website.
In end of May 2015 this is: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
later on that link could be obsolete and should be changed if there is a newer version out.

Newer Mac OS Versions are not shipped any more with the JRE, so they have to download that too.

=== Firefox ===
Selenium is testing in the browser Firefox. The selenium version is not that quick with the updates, as the Firefox browser, if the test is not executable, then it can be that you manually have to install an older version of Firefox.
Sadly that can be a try and error thing. To get older versions of Firefox: https://ftp.mozilla.org/pub/mozilla.org/firefox/releases/ here you will find many folders. Just try the first one that came before the Firefox version that you have been using (and that did not work). In the version folders you will find folders for all the different operating systems.

‎

=== configure test system variables ===

[[File:Acceptance.suite.dist.yml rename.png|thumbnail|left|Screenshot of file structure]]

In your the folder that you installed, downloaded, pulled (git) the project, you have to rename the "''acceptance.suite.dist.yml''" file to "''acceptance.suite.yml''" and configure the parameters to your system variables.
<source lang="php">
config:
JoomlaBrowser:
url: 'http://localhost/tests/joomla-cms3'
# the url that points to the joomla installation at /tests/system/joomla-cms
browser: 'firefox'
window_size: 1024x768
[...]
</source>
[[File:Run Command vendor bin robo test-acceptance.png|thumbnail|test:acceptance]]
Once your machine is able to run tests (see ''The Joomla Browser Module''), you are able to start working.

Check the contents of the /tests/ folder in weblinks and try to understand the structure of the tests.
For each function you have a directory and sometimes a configuration file, both will have the corresponding name.
* FunctionName.yml - these files contain configurations for the function folders
* FunctionName - contains the ''FunctionName'' test
* joomla-cms3 - contains the latest Joomla! installation

After that check the tasks are at: https://github.com/joomla-extensions/weblinks/issues/47

== The principles for writing a test: Readability and Performance ==
In Joomla we give priority to Readability over Performance, even when performance is a must.

To explain that let me show an example: Let's say that we want to fill a field Username in a login form.

<source lang="html4strict">
<form action="administrator/index.php" method="post" id="form-login">
<label for="username_field">Username</label>
<input name="username_field" tabindex="1" id="username_field" type="text" size="15" />
...
</source>

the most performant way to fill that form field would be:

<source lang="php">
$I->fillField('#username_field', 'Mark');
</source>

And usually we would move that to a page object element ending in:
<source lang="php">
$I->fillField(\LoginPage::$username, 'Mark');
</source>

However Codeception is a smart framework and it adds some magic to it's methods (see: https://github.com/Codeception/Codeception/blob/2.0/src/Codeception/Module/WebDriver.php#L511-L513). It allows me to write more readable tests (keeping performance hight).

If we do this:
<source lang="php">
$I->fillField('Username', 'Mark');
</source>

Codeception will be smart and will search first in the page if there is any "LABEL" called Username. That is a fast operation, so performance will be affected just a little. And instead we have written less code than in previous examples.

Note: sometimes this tricks are not always possible, labels are not always there or there are some elements hidden that shows and hides depending on a Javascript. All these special cases would require a Page element.

Still there is a definitive method of using locators that made them readable and performant called: strict Locators see [[Testing_Joomla_Extensions_with_Codeception#Writting_reliable_locators]].

With them we do:

<source lang="php">
$I->fillField(['id' => 'username_field'], 'Mark');
</source>

In conclusion we have more readable tests and less code to maintain while keeping performance. That is a win!

== Setting Up Codeception ==
=== setting up the repository ===
'''clone the directory'''

# Fork [https://github.com/joomla-projects/com_localise com_localise]
#
# Git clone git@github.com:*your-github-profile-name*/com_localise.git

=== Testing with Codeception ===

There are two ways to get and run codeception, via PHAR or via Composer. Using '''Composer is recommended''' (because we are using in some tests the Codeception 2.1 development version not available in the composer.phar).

*'''Using Composer'''

You need to have Composer in your system, if not download it from here: https://getcomposer.org/

Step 1: composer update

Step 2: run Codeception by doing: php vendor/bin/codecept build

*'''Codeception.phar'''

Linux Machine : wget http://codeception.com/codecept.phar

Windows Machine: Download from [http://codeception.com/install codecept.phar]

Step1 : php ./codecept.phar build

=== Running the Test ===
Run Selenium server
<source lang="bash">
# Download
curl -O http://selenium-release.storage.googleapis.com/2.45/selenium-server-standalone-2.45.0.jar

# And start the Selenium Server
java -Xms40m -Xmx256m -jar /Applications/XAMPP/xamppfiles/htdocs/selenium/selenium-server-standalone-2.45.0.jar
</source>
Rename tests/acceptance.suite.dist.yml to tests/acceptance.suite.yml
<source lang="bash">
Step 1: Modify the configuration at tests/acceptance.suite.yml to fit your server details.
</source>

<source lang="bash">
Step 2: php codecept.phar run
</source>
with --steps to see a step-by-step report on the performed actions.

<source lang="bash">
php vendor/bin/codecept run --steps
</source>

with --html. This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in tests/_output/ directory.

<source lang="bash">
php vendor/bin/codecept run --html
</source>

To activate the debug mode in Codeception just add the parameter --debug when you run the tests:

<source lang="bash">
php vendor/bin/codecept run acceptance --debug
</source>

== Best Practices at Testing ==
=== Writting reliable locators ===
Writing good locators can be tricky. The Mozilla team has written an excellent guide titled [https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/ Writing reliable locators for Selenium and WebDriver tests].

If the locator is an array, it should have a single element, with the key signifying the locator type (`id`, `name`, `css`, `xpath`, `link`, or `class`) and the value being the locator itself. This is called a "strict" locator. Examples:

<pre>
* ['id' => 'foo'] matches `<div id="foo">`
* ['name' => 'foo'] matches `<div name="foo">`
* ['css' => 'input[type=input][value=foo]'] matches `<input type="input" value="foo">`
* ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches `<input type="submit" value="foobar">`
* ['link' => 'Click here'] matches `<a href="google.com">Click here</a>`
* ['class' => 'foo'] matches `<div class="foo">`
</pre>

=== How to use URLs ===
Codeception documentation suggests to use URL's as properties of a Page Object:

<source lang="php">
$I->amOnPage(JoomlaInstallationConfigurationPage::$URL);
</source>

Instead of hardcoding the url in the test:
<source lang="php">
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

The pros of this approach is:
- first way is more readable for non developers.
- it helps to make tests more maintenable in the case of a url change in the system

However in joomla a change in an url is rare, and if it happens changing it will just be a Find&Replace task. I Joomla test we want to have the benefit of both, the url and a representative name that describes the page where we are going. That will make our tests more readable. Thus, we will write the urls the following way:

<source lang="php">
$I->amGoingTo('go to Create New Banner page at Joomla Administrator');
$I->amOnPage('/administrator/index.php?option=com_banners&view...');
</source>

=== Working with Hidden Elements ===
Selenium can't interact with elements that are not visible:

<source lang="html4strict">
<a href="http://www.joomla.org" style="display: none;" id="joomla_site">go to joomla</a>
</source>

In this case you can't do:
<source lang="php">
$I->click('go to joomla');
</source>

Usually this happens when you need to wait for a Javascript animation that end up showing that element, so in this case you will need to do this:
<source lang="php">
$I->waitForElementVisible('#joomla_site');
$I->click('go to joomla');
</source>

=== When do not use contains ===
We do not recommend to use the function contains on XPath because is not specific and can create false positives at tests.
See: https://github.com/joomla-projects/GSOC-Webdriver_system_tests_for_CMS/pull/99#issuecomment-69004191
=== Always add Strict Locators to your tests ===
Performance in tests is very important. You can reduce dramatically the time spent on a test with just adding a few extra locators. For example, the following code pertains to a test:

<source lang="php">
// see($text, $selector = null)
$I->see('Your article has been published');
</source>

In the previous code we are not facilitating the "Selector" so Codeception will have to search for the element in all the HTML. Doing this instead:

<source lang="php">
$I->see('Your article has been published', ['id' => 'messages']);
</source>

the tests went from: Time: 1.17 minutes
to: Time: 49.18 seconds

You can see this video of a real example: http://www.youtube.com/watch?v=0JCv0BR2yZY

Losing 30 seconds in every Assertion can delay your tests dramatically. Therefore, remind always to add xPath locators to all your Assertions.
[[Category:Automated Testing]]

==== Using locators in $I->see ====
Do not use ''see'' without locator:
<source lang="php">
// Wrong:
$I->see('Your article has been published');

// Right:
$I->see('Your article has been published', ['id' => 'messages']);
</source>

==== Using locators in $I->waitForText ====
Do not use ''waitForText'' without locator:
<source lang="php">
// Wrong:
$I->waitForText('Finalisation');

// Right:
$I->waitForText('Finalisation', 10, ['css' => 'h3']);
</source>

Incase of an element has multiple css classes, When Using CSS Locators make sure you use more specific class as locator:
<source lang="php">
// Wrong:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert']);

// Right:
$I->waitForText('Item Succesfully Created', 10, ['class' => 'alert-success']);
</source>
A page could have mutiple elements which can have ''alert'' css class associated, hence being more specific helps.

==== How much time should I wait for an Element or Text? ====
You may have noticed that the second parameter in the I waitForText is an integer that represents how much "time to wait" in seconds:

<source lang="php">
$I->waitForText('a text to wait for', 10, ['...' => '...']);
</source>

But, how much time is the right time to wait for a text?

PHP maximum execution time before returning a Fatal Error for timeout is set by default to 30 seconds. We suggest to set it for 10 seconds. A waitForText over 10 seconds will definitely mean that something is not performing well.

=== Quote and Double Quotes in Compex XPaths ===
Sometimes you will have to write XPaths that looks like:

//button[@onclick='Joomla.submitbutton("config.save.application.apply")']

When moved to a Page Object you will probably will face this situation:

[[File:System_tests_error_escaping_quotes_on_xpaths.png|framed|center|Typical issue when you write a long XPath in a Page object]]

To avoid it remind to escape the quotes:

<source lang="php">
// Wrong
public static $elements = array(
'Save' => "//button[@onclick="Joomla.submitbutton('config.save.application.apply')"]"
);
// Right
public static $elements = array(
'Save' => "//button[@onclick=\"Joomla.submitbutton('config.save.application.apply')\"]"
);
</source>

===Generating txt/html scenarios===
Codeception allows you to generate user-friendly text scenarios from scenario-driven from Cest and Cept php test (see http://codeception.com/docs/reference/Commands#GenerateScenarios).

===Don't use double quotes, use single quotes instead===
Do not use double quotes (") for surrounding strings:
<source lang="php">
$I->waitForText("Congratulations! Joomla! is now installed.", 30);
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text ""Congratulations! Joomla! is now installed.""," 30"

If you use single quotes instead:

<source lang="php">
$I->waitForText('Congratulations! Joomla! is now installed.', 30);
</source>

You will get the right expected result:

I wait for text 'Congratulations! Joomla! is now installed.'," 30"

The reason of not being able to use double quotes is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

===Do not leave spaces between parameters in Cepts===
See the two lines:
<source lang="php">
// Wrong
$I->waitForText('Main Configuration', 10, 'h3');
// Good
$I->waitForText('Main Configuration',10,'h3');
</source>

If you do, when you [[Testing_Joomla_Extensions_with_Codeception#Generating_txt.2Fhtml_scenarios|generate the scenarios]] you will get this bad result:

I wait for text 'Main Configuration'," 10"," 'h3'

The reason that you are asked to not add spaces between parameters is due to a bug in Codeception humanize funtions, see issue: https://github.com/Codeception/Codeception/issues/1847

Testing Joomla Extensions with Codeception

2015-05-25T11:09:03Z

Javiparati: /* Always add xPath locators to your tests */

Testing Joomla Extensions with Codeception

2015-05-25T11:00:56Z

Javiparati:

Testing Joomla Extensions with Codeception

2015-05-05T10:20:32Z

Javiparati: /* Best Practices at Testing */ adding best practices for Locators

Testing Joomla Extensions with Codeception

2015-04-23T11:15:01Z

Javiparati: /* The principles for writing a test: Readability and Performance */

Testing Joomla Extensions with Codeception

2015-04-23T11:14:06Z

Javiparati: Add Joomla Browser info

Testing Joomla Extensions with Codeception

2015-04-10T09:25:25Z

Javiparati: /* Don't use double quotes, use single quotes instead */

Testing Joomla Extensions with Codeception

2015-04-10T08:45:17Z

Javiparati:

Testing Joomla Extensions with Codeception

2015-04-10T08:44:20Z

Javiparati:

Testing Joomla Extensions with Codeception

2015-04-02T09:43:49Z

Javiparati: /* How much time should I wait for an Element or Text? */

Testing Joomla Extensions with Codeception

2015-04-02T09:43:30Z

Javiparati: /* Using locators in $I->waitForText */

Testing Joomla Extensions with Codeception

2015-04-02T07:37:02Z

Javiparati: /* Using locators in $I->waitForText */

Testing Joomla Extensions with Codeception

2015-03-27T11:37:04Z

Javiparati: /* Best Practices at Testing */

Testing Joomla Extensions with Codeception

2015-03-27T11:26:56Z

Javiparati: /* The principles for writing a test: Readability and Performance */

Testing Joomla Extensions with Codeception

2015-03-27T11:25:24Z

Javiparati: /* The principles for writing a test: Readability and Performance */

Testing Joomla Extensions with Codeception

2015-03-27T11:24:56Z

Javiparati: /* The principles for writing a test: Readability and Performance */

Testing Joomla Extensions with Codeception

2015-03-27T11:21:21Z

Javiparati: /* The principles for writing a test */

Testing Joomla Extensions with Codeception

2015-03-27T11:20:46Z

Javiparati: /* Structure of a test */

Testing Joomla Extensions with Codeception

2015-03-27T11:02:40Z

Javiparati: /* How to use URLs */

Testing Joomla Extensions with Codeception

2015-03-27T10:59:52Z

Javiparati: /* How to use URLs */

Testing Joomla Extensions with Codeception

2015-03-27T10:58:37Z

Javiparati: /* Best Practices at Testing */

Testing Joomla Extensions with Codeception

2015-03-03T19:31:27Z

Javiparati: /* What is Codeception? */

Testing Joomla Extensions with Codeception

2015-03-03T19:28:06Z

Javiparati: /* What is Codeception? */

Testing Joomla Extensions with Codeception

2015-03-03T19:08:32Z

Javiparati: /* Quote and Double Quotes in Compex XPaths */

Testing Joomla Extensions with Codeception

2015-03-03T19:08:00Z

Javiparati: /* Quote and Double Quotes in Compex XPaths */

File:System tests error escaping quotes on xpaths.png

2015-03-03T19:06:07Z

Javiparati:

== Licensing ==
{{JEDL}}