browser: update finders-filters doc examples. add link to external css selectors site (#736)

MykolaGolubyev · web-flow · commit bb8d01b744ee · 2020-12-04T11:51:44.000-05:00
diff --git a/webtau-docs/znai/UI/finders-and-filters.md b/webtau-docs/znai/UI/finders-and-filters.md
@@ -6,27 +6,33 @@ type: two-sides
 
 Finders in webtau is the initial web element selection that could select one or more elements.
 
-# By CSS
+# CSS Finder
 
-Use `$` to select an element by a given `css` selector.
+Use `$` to select an element by a given `css` selector ([Read W3Schools CSS selectors](https://www.w3schools.com/cssref/css_selectors.asp) to learn all kind of CSS selection techniques).   
 
-:include-file: doc-artifacts/snippets/finders-filters/byCss.groovy
+:include-file: doc-artifacts/snippets/finders-filters/byCss.groovy {title: "example of selecting by id"}
 
 If more than one element is matched, the first one will be used for actions and assertions.
 
-:include-file: doc-artifacts/snippets/finders-filters/byCssFirstMatched.groovy
+:include-file: doc-artifacts/snippets/finders-filters/byCssFirstMatched.groovy {title: "example of selecting by nested tags"}
 
 While `click` and `sendKeys` will always work on a first element only, the matchers can work with a list of things.
 
 :include-file: doc-artifacts/snippets/finders-filters/byCssAllMatched.groovy
 
 Note: declaring element this way will not trigger element search right away.
 
-:include-xml: doc-artifacts/snippets/finders-filters/flat-menu.html {rightSide: true, paths: ["div.div[0]", "div.div[1].ul.li[0].a"]}
+:include-meta: {rightSide: true}
+
+:include-empty-block:
+
+:include-xml: doc-artifacts/snippets/finders-filters/welcome.html 
+
+:include-xml: doc-artifacts/snippets/finders-filters/flat-menu.html {paths: ["div.div[0]", "div.div[1].ul.li[0].a"]}
 
 # Filters
 
-You can use filters to narrow down elements selected by finders like `css`.
+You can use filters to narrow down elements selected by finders.
 
 Filter comes in a way of `get` method. Parameter is one of the following 
 * Element number
diff --git a/webtau-docs/znai/UI/page-element-and-value.md b/webtau-docs/znai/UI/page-element-and-value.md
@@ -1,6 +1,26 @@
+# Element Selection
+
+Use `$('css-selector')` to select a page element.
+
+```groovy {title: "select by id"}
+$('#element-id')
+```
+
+```groovy {title: "select by class"}
+$('.label')
+```
+
+```groovy {title: "select by attribute"}
+$('[data-test-id="my-id"]')
+```
+
+[Read Finders And Filters](UI/finders-and-filters) to learn how to select elements using more advanced techniques. 
+
+[Read W3Schools CSS selectors](https://www.w3schools.com/cssref/css_selectors.asp) to learn all kind of CSS selection techniques.   
+
 # Lazy Element 
 
-When you use `$('.css')` you create instance of `PageElement`. 
+When you use `$('css-selector')` you create an instance of `PageElement`. 
 
 `PageElement` represent an element that is present or *will be present* on a web page. It is safe to declare an element
 before you open a browser or navigate to the page you need to test.
diff --git a/webtau-feature-testing/src/test/groovy/org/testingisdocumenting/webtau/featuretesting/WebTauBrowserFeaturesTestBase.groovy b/webtau-feature-testing/src/test/groovy/org/testingisdocumenting/webtau/featuretesting/WebTauBrowserFeaturesTestBase.groovy
@@ -140,7 +140,8 @@ class WebTauBrowserFeaturesTestBase {
         ])
 
         extractHtmlSnippets(root, 'finders-and-filters.html', [
-             'flat-menu.html': '#menu'
+                'welcome.html': '#welcome-wrapper',
+                'flat-menu.html': '#menu'
         ])
     }
 
diff --git a/webtau-feature-testing/src/test/resources/finders-and-filters.html b/webtau-feature-testing/src/test/resources/finders-and-filters.html
@@ -18,7 +18,9 @@
 <body>
 <div id="simple-case">
     <div>
-        <div id="welcome">hello</div>
+        <div id="welcome-wrapper">
+            <div id="welcome">hello</div>
+        </div>
         <div id="menu">
             <ul>
                 <li>

Original file line number	Diff line number	Diff line change
`@@ -140,7 +140,8 @@ class WebTauBrowserFeaturesTestBase {`
`140`	`140`	`])`
`141`	`141`
`142`	`142`	`extractHtmlSnippets(root, 'finders-and-filters.html', [`
`143`		`- 'flat-menu.html': '#menu'`
	`143`	`+ 'welcome.html': '#welcome-wrapper',`
	`144`	`+ 'flat-menu.html': '#menu'`
`144`	`145`	`])`
`145`	`146`	`}`
`146`	`147`