Path (DollarX - Java version 0.63 API)

All Known Implementing Classes:

BasicPath, SingleBrowserPath
```
public interface Path
```
The heart of DollarX is the definition of Paths that represent W3C elements, whether in the browser or in a document. Path describes an element, or elements, using API that emulates regular description in English, and can represent almost any element that can be expressed as the XPATH. Path is immutable - any additional constraint creates a new Path instance and does not change the original one. It is important to remember that defining new Paths is very cheap, since it does not interact with the browser. For example, in selenium, if we want to define a WebElement inside another WebElement, it must involve interaction with the browser (which involves potential race conditions):
```
 
   WebElement wrapper = driver.findElement(By.cssSelector("div.foo"));
   WebElement field = wrapper.findElement(By.cssSelector(".bar"));
 
 
```
In DollarX it will look like:
```
   final Path wrapper = element.withClass("foo");
   final Path field = element.withClass("bad").inside(wrapper);
 
```
Several points to note:

=======================

1. Once defined, Path values are final and can be reused without cost, as opposed to functions.

2. Creating arbitrarily complex Path is easy this way. It is far more maintainable than using explicit xpath.

3. Creating Paths has nothing to do with the browser.

4. The API offers many alternative ways to define equivalent Paths. The guideline is: If it means the same in English, it is mapped to an equivalent Path. For example, the following are equivalent:
```
     element.that(hasClass("condition").and(isInside(dialog)));
     element.that(hasClass("condition")).and(isInside(dialog));
     element.inside(dialog).that(hasClass("condition"));
     element.withClass("condition").and(isInside(dialog));
     element.withClass("condition").and(isContainedIn(dialog));
     element.that(hasAncesctor(dialog)).and(hasClass("condition"));

     // if you prefer to break the definition to two steps:
     Path condition = element.withClass("condition");
     condition.inside(dialog);
    
```
5. Path::toString returns a string that reads like english and expresses exactly the definition of the path. This is very useful when troubleshooting.

6. To check what is the xpath a Path is mapped to, call path.getXpath().get()

7. Since it can be used as a wrapper of Selenium WebElement, you are not tied to using only DollarX - but can use it interchangeably with straight Selenium WebDriver.
The pattern in DollarX is to define exactly what you want to interact with or assert, as a Path, and then interact with the browser. This maximizes atomicity and performance, and avoid many of the pitfalls involved with interactions with a dynamic SPA. The standard implementation for Path is BasicPath.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Path`	`after(Path path)` The element appears after the given path
`Path`	`afterSibling(Path path)` The element is a sibling of the given path, and appears after it
`Path`	`ancestorOf(Path path)` The element contains the given path, i.e.
`Path`	`and(ElementProperty... prop)` Alias equivalent to `that(com.github.loyada.jdollarx.ElementProperty...)`.
`Path`	`before(Path path)` The element appears before the given path
`Path`	`beforeSibling(Path path)` The element is a sibling of the given path, and appears before it
`Path`	`childOf(Path path)` The element is a direct child of the given path
`Path`	`containing(Path path)` The element contains the given path, i.e.
`Path`	`contains(Path path)` The element contains the given path, i.e.
`Path`	`descendantOf(Path path)` The element is contained in the given path element, i.e.
`Path`	`describedBy(String description)` A useful method to give a readable description to the path, for example: Suppose that instead of describing it's DOM positions and attributes, you prefer to describe it as "search result".
`Optional<String>`	`getAlternateXPath()`
`Optional<String>`	`getDescribedBy()`
`List<ElementProperty>`	`getElementProperties()`
`Optional<org.openqa.selenium.WebElement>`	`getUnderlyingSource()`
`Optional<String>`	`getXPath()` The Optional xpath is maps to.
`Optional<String>`	`getXpathExplanation()`
`Path`	`immediatelyAfterSibling(Path path)` The sibling right before the element matches the given path parameter
`Path`	`immediatelyBeforeSibling(Path path)` The sibling right after the element matches the given path parameter
`Path`	`inside(Path path)` Element that is inside another element
`Path`	`insideTopLevel()` Returns an element that is explicitly inside the document.
`Path`	`or(Path path)` match more than a single path.
`Path`	`parentOf(Path path)` The element is a parent of the given path
`Path`	`that(ElementProperty... prop)` returns a path with the provided properties.
`Path`	`withClass(String cssClass)` The element has the given class name
`Path`	`withClasses(String... cssClasses)` The element has the given class names
`Path`	`withGlobalIndex(Integer index)` Return the nth occurrence of the element in the entire document.
`Path`	`withText(String txt)` Element with text equals (ignoring case) to txt.
`Path`	`withTextContaining(String txt)` The element has text, containing the given txt parameter.

- Method Detail
  - getUnderlyingSource
```
Optional<org.openqa.selenium.WebElement> getUnderlyingSource()
```
    Returns:
    
    The WebElement that is used as the underlying reference for the Path. In most cases, this Optional is empty.
  - getXpathExplanation
```
Optional<String> getXpathExplanation()
```
  - getDescribedBy
```
Optional<String> getDescribedBy()
```
    Returns:
    
    optional readable functional description of the Path
  - getXPath
```
Optional<String> getXPath()
```
    The Optional xpath is maps to. Note that the prefix that marks it is inside the document (for example; "//" as the prefix of the xpath) can be omitted. This is not a concern - it will be added automatically by DollarX when interacting with the browser.
    
    Returns:
    
    an optional containing the xpath this Path is mapped to. The optional is empty only in case it is used as a wrapper of a WebElement (not the typical case).
  - getAlternateXPath
```
Optional<String> getAlternateXPath()
```
    Returns:
    
    Should not be used unless you are developing for DollarX.
  - getElementProperties
```
List<ElementProperty> getElementProperties()
```
    Returns:
    
    Should not be typically used, unless you are developing for DollarX
  - describedBy
```
Path describedBy(String description)
```
    A useful method to give a readable description to the path, for example: Suppose that instead of describing it's DOM positions and attributes, you prefer to describe it as "search result". Then you'd call: searchResult = myElement.describedBy("search result"); Now, calling System.out.println(firstOccurrenceOf(searchResult)), will print: "first occurrence of search result" This will replace its toString() result.
    
    Parameters:
    
    description - a readable description to that expresses the functionality of the path
    
    Returns:
    
    a new Path similar to the old one but that is described by the given description
  - insideTopLevel
```
Path insideTopLevel()
```
    Returns an element that is explicitly inside the document. This is usually not needed - it will be added implicitly when needed.
    
    Returns:
    
    a new Path
  - or
```
Path or(Path path)
```
    match more than a single path. Example: div.or(span) - matches both div and span
    
    Parameters:
    
    path - the alternative path to match
    
    Returns:
    
    returns a new path that matches both the original one and the given parameter
  - that
```
Path that(ElementProperty... prop)
```
    returns a path with the provided properties. For example: div.that(hasText("abc"), hasClass("foo"));
    
    Parameters:
    
    prop - - one or more properties. See ElementProperties documentation for details
    
    Returns:
    
    a new path with the added constraints
  - and
```
Path and(ElementProperty... prop)
```
    Alias equivalent to that(com.github.loyada.jdollarx.ElementProperty...). Added for readability. Example:
```
      div.that(hasClass("a")).and(hasText("foo"));
 
```
    Parameters:
    
    prop - a list of element properties (constraints)
    
    Returns:
    
    a new Path
  - withText
```
Path withText(String txt)
```
    Element with text equals (ignoring case) to txt. Equivalent to path.that(hasText(txt))
    
    Parameters:
    
    txt - - the text to equal to, ignoring case
    
    Returns:
    
    a new Path with the added constraint
  - inside
```
Path inside(Path path)
```
    Element that is inside another element
    
    Parameters:
    
    path - - the containing element
    
    Returns:
    
    a new Path with the added constraint
  - afterSibling
```
Path afterSibling(Path path)
```
    The element is a sibling of the given path, and appears after it
    
    Parameters:
    
    path - - the sibling element that appears before
    
    Returns:
    
    a new Path with the added constraint
  - immediatelyAfterSibling
```
Path immediatelyAfterSibling(Path path)
```
    The sibling right before the element matches the given path parameter
    
    Parameters:
    
    path - - the sibling element that appears after
    
    Returns:
    
    a new path with the added constraint
  - after
```
Path after(Path path)
```
    The element appears after the given path
    
    Parameters:
    
    path - - the element that appear before
    
    Returns:
    
    a new Path with the added constraint
  - beforeSibling
```
Path beforeSibling(Path path)
```
    The element is a sibling of the given path, and appears before it
    
    Parameters:
    
    path - - the sibling element that appears after
    
    Returns:
    
    a new Path with the added constraint
  - immediatelyBeforeSibling
```
Path immediatelyBeforeSibling(Path path)
```
    The sibling right after the element matches the given path parameter
    
    Parameters:
    
    path - - the sibling element that appears after
    
    Returns:
    
    a new path with the added constraint
  - before
```
Path before(Path path)
```
    The element appears before the given path
    
    Parameters:
    
    path - - the element that appear after
    
    Returns:
    
    a new Path with the added constraint
  - childOf
```
Path childOf(Path path)
```
    The element is a direct child of the given path
    
    Parameters:
    
    path - - the parent element
    
    Returns:
    
    a new Path with the added constraint
  - parentOf
```
Path parentOf(Path path)
```
    The element is a parent of the given path
    
    Parameters:
    
    path - - the child element
    
    Returns:
    
    a new Path with the added constraint
  - containing
```
Path containing(Path path)
```
    The element contains the given path, i.e. the given path parameter is inside the element
    
    Parameters:
    
    path - - the element that is inside our element
    
    Returns:
    
    a new Path with the added constraint
  - contains
```
Path contains(Path path)
```
    The element contains the given path, i.e. the given path parameter is inside the element
    
    Parameters:
    
    path - - the element that is inside our element
    
    Returns:
    
    a new Path with the added constraint
  - ancestorOf
```
Path ancestorOf(Path path)
```
    The element contains the given path, i.e. the given path parameter is inside the element
    
    Parameters:
    
    path - - the element that is inside our element
    
    Returns:
    
    a new Path with the added constraint
  - descendantOf
```
Path descendantOf(Path path)
```
    The element is contained in the given path element, i.e. the given path parameter is wrapping it
    
    Parameters:
    
    path - - the element that is wrapping our element
    
    Returns:
    
    a new Path with the added constraint
  - withGlobalIndex
```
Path withGlobalIndex(Integer index)
```
    Return the nth occurrence of the element in the entire document. Count starts at 1. The following expressions are equivalent: occurrenceNumber(4).of(myElement)); myElement.withGlobalIndex(4); Return the nth occurrence of the element in the entire document. Count starts at 1. For example: occurrenceNumber(3).of(listItem)
    
    Parameters:
    
    index - the number of occurrence
    
    Returns:
    
    a new Path with the added constraint
  - withClass
```
Path withClass(String cssClass)
```
    The element has the given class name
    
    Parameters:
    
    cssClass - the class name
    
    Returns:
    
    a new Path with the added constraint
  - withClasses
```
Path withClasses(String... cssClasses)
```
    The element has the given class names
    
    Parameters:
    
    cssClasses - the class names
    
    Returns:
    
    a new Path with the added constraint
  - withTextContaining
```
Path withTextContaining(String txt)
```
    The element has text, containing the given txt parameter. The match is case insensitive.
    
    Parameters:
    
    txt - the text to match to
    
    Returns:
    
    a new Path with the added constraint

Interface Path

Several points to note:

Method Summary

Method Detail

getUnderlyingSource

getXpathExplanation

getDescribedBy

getXPath

getAlternateXPath

getElementProperties

describedBy

insideTopLevel

or

that

and

withText

inside

afterSibling

immediatelyAfterSibling

after

beforeSibling

immediatelyBeforeSibling

before

childOf

parentOf

containing

contains

ancestorOf

descendantOf

withGlobalIndex

withClass

withClasses

withTextContaining