docu: update locators

docs/usage/locators.md

@@ -166,6 +166,28 @@ element(by.control({
   }
 }));
 ```
+### Common usecases
+
+#### Working with responsive toolbars
+A responsive toolbar may have overflowing content, depending on the screen size.
+This content will be moved to a popover which is open by pressing a toggle button in the toolbar.
+A toggle button will be shown only when there is overflowing content. This is a problem for tests because they should only try to press the button when it's visible and interactable. One way to solve this is to always start the application under test with with a fixed screen size. Another way is to first look for any toggle button - with no restriction on visibility, and then press on it only if it exists:
+```javascript
+var button = element(by.control({
+  controlType: "sap.m.ToggleButton",
+  ancestor: {
+    viewNamespace: "appUnderTest.view.",
+    viewName : "Main",
+    id: "toolbar-overflow"
+  }
+}));
+
+button.isPresent().then(function (isPresent) {
+  if (isPresent) {
+    button.click();
+  }
+});
+```
 
 ## DOM Locators
 All standart `by.` locators from [WebDriverJs](https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_By.html) are supported.

e2e/browser/fixture/apps/browser/app.js

@@ -7,7 +7,6 @@ module.exports = {
     search.attachSearch(function (oEvent) {
       searchQuery.setText(oEvent.getSource().getValue());
     });
-
     var page1 = new sap.m.Page("page1", {
       title: "Page 1",
       content : [
@@ -50,11 +49,77 @@ module.exports = {
         new sap.m.Button({
           id : "hide-nav-btn",
           text : "hide Nav Button",
-            press : function() {
-              page1.setShowNavButton(false);
-            }
+          press : function() {
+            page1.setShowNavButton(false);
+          }
+        }),
+        searchQuery,
+        new sap.m.OverflowToolbar({
+          id: "toolbar-fit",
+          width: "600px",
+          content: [
+            new sap.m.Button({
+              text: "Always Visible",
+              press: "onToolbarButtonPress",
+              layoutData: [
+                new sap.m.OverflowToolbarLayoutData({
+                  priority: "NeverOverflow"
+                })
+              ]
+            }),
+            new sap.m.Button({
+              text: "Mostly Visible",
+              press: "onToolbarButtonPress",
+              layoutData: [
+                new sap.m.OverflowToolbarLayoutData({
+                  priority: "High"
+                })
+              ]
+            }),
+            new sap.m.Button({
+              text: "Should Overflow",
+              press: "onToolbarButtonPress",
+              layoutData: [
+                new sap.m.OverflowToolbarLayoutData({
+                  priority: "Low"
+                })
+              ]
+            })
+          ]
+      }),
+      new sap.m.OverflowToolbar({
+        id: "toolbar-overflow",
+        width: "300px",
+        content: [
+          new sap.m.Button({
+            text: "Always Visible",
+            press: "onToolbarButtonPress",
+            layoutData: [
+              new sap.m.OverflowToolbarLayoutData({
+                priority: "NeverOverflow"
+              })
+            ]
+          }),
+          new sap.m.Button({
+            text: "Mostly Visible",
+            press: "onToolbarButtonPress",
+            layoutData: [
+              new sap.m.OverflowToolbarLayoutData({
+                priority: "High"
+              })
+            ]
           }),
-          searchQuery
+          new sap.m.Button({
+            text: "Overflowing",
+            press: "onToolbarButtonPress",
+            layoutData: [
+              new sap.m.OverflowToolbarLayoutData({
+                priority: "Low"
+              })
+            ]
+          })
+        ]
+      })
       ],
       subHeader: new sap.m.Bar({
         contentMiddle: [search]

e2e/browser/specs/by_control.spec.js

@@ -163,5 +163,49 @@ describe("by_control", function () {
 		}));
 
 		expect(list.getAttribute("id")).toContain("ListPage1");
-	})
+	});
+
+	it("should interact with overflow toolbars", function () {
+		var presentToggleButton = element(by.control({
+			controlType: "sap.m.ToggleButton",
+			ancestor: {
+				id: "toolbar-overflow"
+			},
+			visible: false
+		}));
+		var overflowingButton = element(by.control({
+			controlType: "sap.m.Button",
+			properties: {
+				text: "Overflowing"
+			}
+		}));
+
+		presentToggleButton.isPresent().then(function (isPresent) {
+			if (isPresent) {
+				presentToggleButton.click();
+			}
+		});
+
+		// toggle button should be pressed and overflowing buttons should be shown
+		expect(overflowingButton.isPresent()).toBeTruthy();
+
+		var hiddenToggleButton = element(by.css("#toolbar-fit button[title='More']"));
+		var toolbarButton = element(by.control({
+			controlType: "sap.m.Button",
+			properties: {
+				text: "Always Visible"
+			}
+		}));
+
+		hiddenToggleButton.isPresent().then(function (isPresent) {
+			if (isPresent) {
+				// should not get here as the button is not present
+				hiddenToggleButton.click();
+			}
+		});
+
+		// toggle button should not be visible and therefore not pressed. non-overflowing buttons should be shown
+		expect(toolbarButton.isPresent()).toBeTruthy();
+
+	});
 });