---
Help: Information on impact of upgrading to a newer version of this project
---
!2 Version 3 to 4
The main difference between versions 3 and 4 is that the Maven classpath plugin is no longer included. The plugin did not always work reliably, was no longer being maintained, faster disks make copying dependencies to 'wiki/fixtures' less of an issue and dependency change occur very infrequently.

The impact of no longer bundling this plugin:
 * When running the wiki via Maven one now has to explicitly add ''dependency:copy-dependencies'' to the command line.
  * So instead of using !style_code[mvn compile exec:exec] one should do !style_code[mvn compile dependency:copy-dependencies exec:exec].
  * If dependencies in the !style_code[pom.xml] file are changed, the wiki must be restarted before they are picked up.
  * (The wiki can be started as before when using the standalone.zip version, or an own project based on either the archetype or sample project.)
 * For the wiki pages: the line !style_code[!pomFile ../pom.xml@compile] can be removed (usually present on the top-level suite page).
 * In the !style_code[wiki/plugins.properties] file, the line !style_code[!-SymbolTypes = fitnesse.wikitext.widgets.MavenClasspathSymbolType-!] can be removed.

!2 Version 1.10 to 2.0
The main differences between version 1.10 and 2.0 are in the way elements are found by !-BrowserTest-!. That is also why this is a major version upgrade: the changes will likely impact both the wiki test page content and any fixture subclasses created for test suites using this project.

The most important change in finding elements by !-BrowserTest-! is what is done when an element is ''not'' found: where in version 1.x the commands/methods would return !style_code[false] when no element could be found version 2.0 will instead retry the find operation for a while (up to the configured number of ''seconds before timeout''). If on timeout version 2.0 still has not found the element it will throw an exception. This does mean that one can no longer make test assertions using the ''reject'' script keyword to, for instance, ensure that an element cannot be clicked. To support such usage a new command ''click if available'' is introduced, this will return !style_code[false] if the element cannot be clicked before timeout (so it does retry). Furthermore commands/methods that returned a !style_code[null] String immediately if no element could be found, no wait until the timeout to return that value. The reason for making this change is the dynamic, asynchronous, !-JavaScript-!-based nature of many modern web applications: elements may appear on the page just a little bit slower than Selenium can check things, and that meant that often test scripts needed many explicit waits to make them execute reliably. These explicit waits were cumbersome to write and made test scripts more verbose, distracting from the actual behavior to be tested. So in version 2.0 there is more implicit waiting by the fixture. 

The second major change in finding elements that the heuristics used by !-BrowserTest-! can be bypassed. By specifying a ''<place>'' with a special prefix an explicit Selenium find command can be passed to the commands/keywords. Although this makes tests less readable and maintainable, since technical identifiers are used instead of end-user terms, it also gives extra flexibility writing tests without coding Java. By hiding the technical identifiers in scenarios a balance can be struck between the two approaches. Previously finding by technical identifiers was already possible using some special commands/methods (e.g. !style_code[text by xPath]), these are no longer needed in the 2.0 version, since normal commands/methods have been given the ability. To clean up !-BrowserTest-!'s code, and allow for more uniform test script content, the special commands/methods will be removed.

!3 Wiki Impact
* The heuristic to find elements can be bypassed by specifying an explicit (technical) query as ''<place>''. The supported queries are:
|'''place'''             |'''query'''                                                  |
|id=<id value>           |find the element with the specified id                       |
|name=<name value>       |find the element with the specified name                     |
|link=<link text>        |find the first link with the specified text                  |
|xpath=<xPath expression>|find the first element matching the supplied xPath expression|
|css=<CSS selector>      |find the first element matching the supplied CSS selector    |
* ''value of'', ''enter as'', ''select for'' and ''clear'' no longer look at hyperlinks.
* ''click'' and ''is visible'' prefers hyperlinks to above other elements (such as !style_code[input]s or !style_code[button]) when both match (this only impacts pages where there were multiple exact or multiple partial matches for the same ''<place>'').
* All usage of ''|click by xPath|<xPathExpr>|'' should be replaced by a call to ''|click|xpath=<xPathExpr>|''. This could be done using a scenario called ''click by xPath'' so that individual pages need no change.
* All usage of ''|text by xPath|<xPathExpr>|'' should be replaced by a call to ''|value of|xpath=<xPathExpr>|''. This could be done using a scenario called ''text by xPath'' so that individual pages need no change.
* All usage of ''|wait for xPath visible|<xPathExpr>|'' should be replaced by a call to ''|wait for visible|xpath=<xPathExpr>|''. This could be done using a scenario called ''wait for xPath visible'' so that individual pages need no change.
* All usage of ''|text by class name|<className>|'' should be replaced by a call to ''|value of|css=.<className>|''. This could be done using a scenario called ''text by class name'' so that individual pages need no change.
* A new command/method has been introduced ''seconds before page load timeout'', this controls (only) the time waited for a new page to be returned by the server. Previously this time out was set using ''seconds before timeout''. The latter still sets the maximum page load time (for backwards compatibility), but the new command allows specific control of the page load timeout separate from the timeout when looking for elements to interact with (which is controlled using ''seconds before timeout''). 

!3 Fixture Subclass Impact
* Previously !style_code[waitUntil()] threw an exception to stop the test execution. Now !style_code[waitUntil()] just throws an exception (with screenshot, and page source). If you want to stop the test: please use !style_code[waitUntilOrStop()].
* If you want your code to retry (ignoring !style_code[!-StaleElementReferenceExceptions-!]) but not throw an exception, but have !style_code[null] returned (like !style_code[valueOf()]): please use !style_code[waitUntilOrNull()].
* When writing methods that should retry a couple of times, so that an asynchronous page update is handled transparently from the wiki perspective, instead of using explicit invocations of !style_code[waitUntil()] an annotation can also be used: !style_code[@WaitUntil].
* !-BrowserTest-!'s methods also use the !style_code[@WaitUntil]-annotation to achieve retrying behavior. This has an impact on direct Java calls of these methods, since a direct Java call is not impacted by the annotation. When calling the methods and retry is needed, either ensure the public method invoked by Slim also has the annotation (so that it will retry), or make the call to a !-BrowserTest-! instance obtained via !style_code[!-nl.hsac.fitnesse.slim.interaction.FixtureFactory-!]. This factory will return an instance for which the !style_code[@WaitUntil] is respected on direct Java method invocations.
* The implementation of the protected method !style_code[hasText()] has been changed to that of the old method !style_code[hasTextUnsafe()] which has been removed. The handling of 'stale elements' is now expected to be done in a !style_code[waitUntil()] call and not in individual methods (and that was the difference between the two).
* The implementation of the protected method !style_code[hasText()] has been further changed to trim actual values before comparison, and not use the element's text but !style_code[value]-attribute not only when the text is !style_code[null] but also on empty.
* Protected method !style_code[clickImpl()] has been changed so that it will just return !style_code[false] if another element would receive the click.
