Metamer is testing application and test suite which covers all of RichFaces 4 components and it is able to display them in different skins and also different component containers (called templates - tables, tooltip, etc.).

Metamer Maven Structure

Metamer consists of root module and three submodules:

• root - parent for application and ftest
• application - java-ee application
• ftest-source - the source of test suite

Metamer Application

Metamer is Maven based web application able to be deployed onto JBoss AS 7 (and possibly any other Java EE container) and Tomcat 6 and 7.

Its compile dependencies are RichFaces 4, JSF 2 API, Atmosphere and Validation API (JSR-303).

Source code is available at:

https://github.com/richfaces/richfaces-qa/tree/master/metamer

JSF Page per Component/Feature

• Templates
  • configurable nesting of templates using various container components:
  • root: webapp/templates/template.xhtml
  • templates:
    • plain
    • iteration - a4jRepeat, hDataTable, richDataTable...
    • panels -  richPanel, richTabPanel, richTogglePanel, richAccordion...
• Page Parts
  • template.xhtml - nesting mechanism (see above)
  • header.xhtml - contains general controls
  • footer.xhtml - contains output of VersionBean
• Customization per component (ui:insert in template.xhtml):
  • outOfTemplateBefore - usually contains additional controls for advanced features of components which can’t be covered by customization of attribute values
  • content - contains component nested in all configured templates
  • outOfTemplateAfter - as for outOfTemplateBefore, usually contains attribute list
• Attributes
  • attributes for each component are bound directly from page using following notation:
    • #{componentBean.attributes[‘attributeName’].value}
    • where “attributes” stands for class Attributes extends Map<String, Attribute>
    • attributes are loaded to map from richfaces’s faces-config.xml
    • attributes can have predefined enumeration values using ComponentBean.properties files
• Sepation
  • each component has own package (named like Bean for given component) for component samples
  • in each package are:
    • list.xhtml - the links to all samples
    • simple.xhtml - default component usage (not compulsory)
    • {feature}.xhtml - feature sample

Managed Beans

• per component (and some per component/feature)
• bean.* packages
• RichBean
  • serves common functionality for general tests (actions, action listeners)
• TemplatesBean
  • serves list of templates for user session
• PhasesBean
  • holds the list of phases which request goes through
  • phases provided by RichPhaseListener
• VersionBean
  • provides set of runtime and browser versions
  • output on each Metamer page => can be copied to JIRA’s environment

Model

• provides models collections for iteration
• loaded from XMLs using JAXB
• model.* packages
• exposed in bean Model

Additional Resources

• webapp/resources/*

Running the Application

Metamer needs to be built in several profiles to satisfy compatibility with various runtimes and JSF implementations. To build the application, run bash script build.sh in root directory of Metamer. This script generates several WAR archives with application in directory application/target which can be used in various scenarios:

• metamer-glassfish31.war - to deploy on GlassFish 3.1
• metamer-jbas71.war - to depoly on JBoss AS 7.1.1.Final
• metamer-tomcat7-mojarra.war - with bundled JSF Mojarra reference implementation to deploy on Tomcat 7
• metamer-tomcat7-myfaces.war - with bundled JSF MyFaces to deploy on Tomcat 7
• metamer-jbas6-bundled-mojarra.war - with bundled JSF Mojarra  reference implementation to deploy on JBoss AS 6
• metamer-bundled-myfaces.war - with bundled JSF MyFaces to deploy on JBoss AS 6
• metamer-tomee11.war - to deploy on TomEE 1.1.x

Development of Metamer Application

• Eclipse
• JBDS

Metamer Ftest Source

Written in Arquillian Graphene, they use TestNG test runner.

Base class: AbstractMetamerTest

Listeners

MetamerConsoleStatusTestListener

• gives status of tests on stdout (STARTED/SUCCESS/FAILURE/SKIPPED)

MetamerFailureLoggingTestListener

• logs each failure in predefined structure
• guide How-To Review Failing Tests

MetamerSeleniumLoggingTestListener

• log each failure to selenium-server.log
• simplifies navigation in selenium log

Reusable components

AbstractComponentAttributes

• abstract base for creating classes manipulating with component attributes on page
• simplified configuration of components

DelayTester

• abstract base for testing all kinds of delay (queue, tooltip delay, popup delay, poll and push delay)

PhaseInfo

• obtains information about component lifecycle - can assert triggering specific action in given lifecycle phase

MatrixConfigurator

• sort of test listener (do annotation processing)
• inspects @Use, @Templates and @Inject annotations
• setup test to be ran repeatedly with various configurations  

Model

• model.* package
• reusable pieces of code for testing specific components
• encapsulates component functionality, e.g.:
  • Data Table
  • Autocomplete
  • Tree
  • Panel Menu

Ftest Development

• Development for JBoss AS 7.1.1.Final
  • deploy the metamer-jbas71.war to JBoss AS 7.1.1.Final
  • create or modify .xhtml in the application/src/main/webapp/components, this is the facelet which will be loaded in the test
  • create .java test class in the package for the component, in the ftest/src/test/java/...
  • We are using Arquillian Graphene 2, tests have these specifics:
    • Tests can extend AbstractWebdriverTest, have a look at: method with @Deployment annotation, @Drone WebDriver browser injection point, @ArquillianResource contextRoot, @BeforeMethod loadPage
    • We are using Page Object pattern, have a look at @Page annotation
    • We are using Page Fragments pattern, have a look at @FindBy annotations, for more information see Graphene documentation
  • to run the tests one needs to be in the metamer/ftest directory and issue:
    • mvn clean verify -Pcontainer-profile
      • where container profile is on of the profiles defined in the richfaces-qa parent pom.xml - e.g. jbossas-remote-7-1 or jbossas-managed-7-1
    • by default Firefox browser is used, to change it for e.g. Chrome follow please instructions from Arquillian guide for remote-reusable browsers

Issue verification

• In order to verify an issue an existing page facelet of metamer should (and then referenced in the JIRA issue) or if it is needed new one created
• Make a comment in the JIRA issue what facelet reproduce the issue, and also steps to reproduce it
• when creating new facelet for the issue, create it under affected component with the name of issue number (e.g. rf-15422.xhtml)
  • the newly created issue should also contain a steps to reproduce the issue, e.g. <r:panel header="steps to reproduce">1. blah blah <br /> 2. blah blah</r:panel>
  • list the newly created facelet also in the list.xhtml, together with the issue description and reference
• create also a test class with the same name (e.g. RF15422) under the package for the affected component
• annotate test method with

    @Test(groups = "Future")

    @IssueTracking(value = { "https://issues.jboss.org/browse/RF-15422" })

• try to reuse existing backing beans, otherwise create new ones in the package: metamer / application / src / main / java / org / richfaces / tests / metamer / bean / issues
  

Metamer RichFaces Bug Report Guidelines

1. find if JIRA doesn’t exists already (use preconfigured filter) for looking for RF4 JIRAs:
   • something like project=RF AND affectedVersion >= '4.0.0.Alpha1' AND summary ~ "test"
2. file new RF project Bug (RFPL for docs)
   • choose components (probably component-* for specific component bug)
   • choose affects versions
   • for Metamer:
     • Environment - use Metamer’s footer with detailed runtime, browser and libs info
     • Steps to Reproduce, e.g.:
       1. open http://localhost:8080/metamer/faces/components/richList/simple.xhtml
       2. set @first=5
       3. set @rows=10
       4. EXPECTED: to show 10 items
       5. ACTUAL: shows 15 items
     • sometimes no need for Description
     • screenshot may be necessary
   • otherwise:
     • Description with code sample (Bean + JSF)
     • use {code} for formatting code samples and stack traces
     • eventually provide specific version control revision or WAR directly