Gutenberg by Subject7 is an XPath generation engine. It uses hints provided by users to create robust and resilient to change XPaths. 

Gutenberg can be optionally installed as an extension to Google chrome, but will automatically be available on the automation browser when  the user when launches a test case locally. We suggest to use the automation browser extension, that way you get the most recent updates with local player.

Manual Installation

1- Add the plugin to Chrome from this link Chrome Web Store which will install the plugin automatically. If Web Store is locked by your administrator, download the plugin from this link and follow the steps below:

A- From Google Chrome, click on the 3 dots under the close button, then go to More tools > Extensions

B- Make sure that Developer Mode is turned on (at the top right of the page). If it's disabled, turn it on.

C- Drag and drop the plugin file to Google Chrome to install it. Alternatively, you can extract the contents of the .zip file to a folder and click Load unpacked from Chrome to select the folder.

2- You will be asked if you have a Subject7 account. Click Yes.

3- Enter the host (your Platform's website), username and password for your account. You can also use API Key instead. Click Test to see if access is successful.

4- Click Save. You will get a popup to indicate that your settings have been saved and the XPath Templates have been received from your user to Gutenberg.

5- You will notice that the Gutenberg icon has appeared on Chrome as below:

Automatic Installation

1- To use Gutenberg directly on the test automation browser without the need to install it, simply perform a local execution (with a Goto_URL step)

2- When the test automation browser page opens, click Extensions icon on Chrome to see the loaded extension. As highlighted below, you will see Gutenberg Smart XPath icon.

3. If you have an API Key set up under Manage API Key, Gutenberg will automatically get authenticated and ready for you to use.

Using Gutenberg

To use Gutenberg, follow the steps below:

1- Navigate to the website where you need to define an object/element

2- Click on Gutenberg icon on your browser to activate the plugin. 

3- Click on the object/element you need to define and a popup will appear.

4- On this popup, you will need to enter a Hint for the locator to locate the object/element. This can simply be the label written on the object/element or a tool tip, etc.

5- To show you an example, we have used https://reference.subject-7.com to locate the element associated with Register button from the main page.

• The entered hint is Register which has identified an XPath. 
• Frames will automatically be included if the element you are interacting with is located in a frame
• Inner and outer frames are also identified and separated by ( ; ) automatically for the platform to read during execution
• Popups field can be used to include a popup name if the element you are interacting with is in not on the main window, but rather on a popup window

6- To test that you selected the correct XPath, click Test. Gutenberg will navigate to the web page and flash around the selected object. If the object is incorrect, make any changes to the hint and try again. The following simulation video will show you how this is done:

7- To save the XPath to Subject7 without having to copy the XPath and entering it manually (make sure to do the same as in step 3 in Manual Installation section above), enter the Web Page name and Type, then click Push to Server button. (In this case, we have selected a button on reference_main_page Page). You will see a popup asking for confirmation. Click OK.

8- Go back to Subject7 and navigate to Web Locators. You will notice that the locator has been created automatically and is now available for you to use.

The following video shows how the Register button is defined, pushed to Subject7 and tested in a local run.

9- In order to stop the Gutenberg from continuing to define locators, simply click on the icon again to disable it. 

XPath vs CSS Selector

Gutenberg can also generate CSS Selectors for you, but pushing them to server depends on whether you have enabled "Save CSS Selector instead of XPath when possible" checkbox in the extension options.

Here's how it works:

• If you have both XPath and CSS Selector generated and the option is enabled in extension options, only CSS Selector is pushed to server
• If you have both XPath and CSS Selector generated and the option is disabled in extension options, only XPath is pushed to server
• If you have only CSS Selector generated and the option is enabled in extension options, only CSS Selector is pushed to server
• If you have only CSS Selector and the option is disabled in extension options, only CSS Selector is pushed to server
• If you have only XPath and the option is enabled in extension options, only XPath is pushed to server
• If you have only XPath and the option is disabled in extension options, only XPath is pushed to server
• If XPath and CSS fields are empty (manually removed), "Push To Server" button will be disabled

Advanced Functions

Gutenberg has some advanced functions that appear when you click Advanced button highlighted below

1- Distance: Since Gutenberg requires hints to find XPaths for your elements, you can use hints of other elements as an anchor point to traverse to your element. The distance between the anchor and your element may vary and you have the option to determine the distance (Very Close, Close, Middle, Far, Very Far). For example, the below image shows a text "podcast" which is very far from the target element (hyperlink). If you have several elements with the same text where you would like to use one as an anchor point, you can determine the distance which controls the closest or the farthest element to be used.

2- Match Case: this option allows Gutenberg to match the case of your hint with the text on screen. If the text you entered is not the same, the XPath will not be generated until your hint is a match.

3- Full Match: this option allows Gutenberg to provide an XPath using an exact match of the hint text.

For example, an XPath without full match: //a[contains(text(),'LOGIN')]

while an XPath with full match: //a[text()='LOGIN']

4- Use ID Attribute: this option allows Gutenberg to generate XPaths using Web IDs if they are available. If not available, it would generate a standard XPath. Note that if your Web IDs are dynamic (meaning they change when you refresh), it's best to avoid using them as your tests will fail when these Web IDs are not found.

Shadow DOM

If your web application uses Shadow DOM, Gutenberg extension can generate CSS Selectors for you to use, as XPath does not work on Shadow DOM. 

1. By clicking on an element inside a shadow root, Gutenberg will automatically notify you that the element is inside the Shadow DOM and you will not be required to enter a hint. 

2. Click Generate to move to the next step where you can click Copy CSS

3. In order to use this CSS Selector in your test case, you will need to create a Web Locator. Click CSS Selector instead of XPath and paste the value in the CSS Selector field:

4. You can now use the locator in your test case.

XPath Templates

Gutenberg automatically loads the XPath Templates from your user when you add your credentials in the configuration page. By doing so, Gutenberg can generate specific XPaths using your templates same as with Recorder.

If you have made changes to your XPath Templates and would like to use the new changes, click Reload Templates button after clicking anywhere on the screen.

Please check Subject7 Recorder (BETA) for more information on XPath Templates.