When it comes to ensuring your transaction runs smoothly, Content checks are the most valuable tools at your disposal. A well-used content check can make all the difference in a transaction. In general, the purpose of content checks is to verify that the previously executed action (e.g., clicking a link, logging in/out, navigating to a page) completed successfully. Since transaction monitors run using a script, adding content verification is invaluable to ensure the transaction runs smoothly and provides you with accurate information regarding your website.

Content checks are free, so we encourage you to use them! Content checks add value to your transaction monitor after any action that generates new content on the page.

Because a content check in your transaction script waits for the indicated content to load, you have two added benefits.

  • First, you know for sure that the navigation ended on the correct page by verifying the presence of page-specific content.
  • Secondly, you know for sure that the page loaded correctly and fully by waiting for the indicated element to finish loading. Verifying that the element finished loading helps to prevent the transaction from proceeding with the next action too quickly.

When to use content checks

In general, the purpose of a content check is to verify the successful completion of the previously executed action. You should add content checks after any action that changes the page's content in any way. By using a content check, you explicitly test if specific actions in the script had the desired result in the browser. Examples of when to use a content check include:

  • after entering credentials and clicking the "login" button,
  • after clicking on a product link on an e-commerce site,
  • after logging out, or
  • after navigating to a new page.

You should also use a content check to verify that an auto-completed text field worked, a table populated properly with data, or a script successfully ran.

How to add content checks using the visual editor

To add a content check using the visual editor,

  1. Click the Add action button.
  2. Select the appropriate action type from the pop-up based on your situation. Notice that the content check action types have a green "Test" label in the available actions list (see figure below).
    Screenshot: The action selection dialog box

After making your selection, the new action appears in the SST editor (See figure below. Your setting options may vary depending on the action type selected). This screenshot displays the Test element content action type. The Test element content action requires the use of a CSS or XPath selector to point to a specific element. You use the drop-down menu to switch between the two selector types.

Screenshot: Test element content

After selecting a selector type (CSS/XPath) and entering the selector, you can choose a match condition. Uptrends defaults the match condition drop-down menu to contains, which looks for a match to the value you indicate. You have other available options as well:

  • Does not contain,
  • Matches regular expression, and
  • Does not match regular expression.

Finally, you enter the value you’d like Uptrends to check for in the indicated element in the example text field.

The Test document content check type does not support adding a CSS or XPath selector. Likewise, the Wait for element check type does not support adding a string value for testing the indicated element.

The other action settings are optional.

  • Description: Add a description for your content check, such as "Test if the login was successful."
  • Failure message: What to display if this content check generates an error, such as "Login was not successful."
  • Wait until: Set the wait condition for this monitor check. Refer to the Wait for element article. Note: Wait Until isn't available for the Test document content type.
  • Wait timeout: How long, in milliseconds, Uptrends should wait for the content to appear. The default is 30,000 ms. For most cases, we recommend that you stick to the default. However, in certain cases, you may find that increasing the timeout useful. Be careful not to increase the timeout by too much, as there is an absolute upper limit to how long a complete transaction may take. Please note, increasing or decreasing the wait timeout does not affect any measured time metrics for the transaction.

Content check types

Currently, in the SST editor, you have the option to choose between three separate types of content checks.


Test document content

The Test document content type is the most straightforward one available. The Test document content type looks for the specified content anywhere in the page document regardless of whether or not the content is visible. Not all text that exists in the page document or DOM appears on the page. However, since the Test document content test type checks the HTML document rather than the page as the browser loads the content, you can check for "invisible" text. Since the Test document content type does not check the loaded page contents, you can't use XPath or CSS selectors to point to a specific element. However, we do support using a regular expression to search for specific patterns in the DOM content.

If you chose to work directly with the JSON transaction script rather than use the visual editor, the Test document content check type needs to have the following format:

{
  "testDocumentContent": {
   "value": "Example content in the DOM",
   "testType": "Contains",
   "timeoutMs": 30000,
   "description": "This check will test the page DOM for the specified content.",
   "failureMessage": "Example failure message"
  }
}

Please note, because the timeoutMs, description, and failureMessage parameters are optional, so you can leave them out.


Test element content

For the Test element content test type, Uptrends checks a specific element on the page for content you specify. The Test element content check allows for more specific and robust checks compared to the Test document content type. For most purposes, we recommend you use the Test element content type. The Test element content type requires that you point to a specific element on the page using a CSS or XPath selector and define a content string the element should contain. Doing so leads to very robust checks that verify the successful completion of actions the script executes.

If you’re working directly with the JSON transaction script, the Test element content check type needs to have the following format:

{
  "testElementContent": {
   "value": "Example text",
   "testType": "Contains",
   "element": {
    "xpath": "//*[@id='exampleId']"
  },
  "timeoutMs": 30000,
  "description": "Test  the element with the indicated XPath selector for the specified content.",
  "failureMessage": "Example failure message"
  }
}

Please note, because the timeoutMs, description, and failureMessage parameters are optional, you can leave them out. The available testType parameter values are Contains, DoesNotContain, MatchesRegex’ and DoesNotMatchRegex. This example verifies that the (example) element with XPath selector //*[@id=’exampleId’] contains the string "Example text." Of course, CSS works as well: “css”:”#exampleId”.


Wait for element

The Wait for element test type is identical to the Test element content type, except, in this case, the element does not need to contain any text content. You can use the Wait for element test type to check for empty elements, for example, <div> elements without any text in them, images, and buttons.

If you’re working directly with the JSON transaction script, the Wait for element check type needs to have the following format:

{
 "waitForElement": {
  "element": {
   "xpath": "//*[@id='exampleId']"
 },
 "timeoutMs": 30000,
 "description": "Verify that the element with the indicated XPath selector exists on the page.",
 "failureMessage": "Example failure message"
 }
}

Please note, because the timeoutMs, description, and failureMessage parameters are optional, you may leave them out.

Negative content checks

Instead of verifying that specific content does exist in the DOM or appears on the page, you may need to verify that certain content does NOT exist on the page. For example, you may wish to get an alert if a certain error message appears on your page. To test that specified content does not appear on the page, use negative content checks. If the specified content appears on the page, the monitor errors.

To use a negative content check, add either a Test document content or Test element content check type. Then, set the matching condition from the default value of contains to either does not contain or does not match regular expression.

When using a negative content check, if the transaction encounters the specified element or content, the transaction stops and returns an error. If the element or content does not appear, the transaction continues as normal.

Content check quality

To ensure the best results from your content check, select a unique element on the page that contains unique text that resulted as from the previous action. A useful content check is a definitive and exclusive test of an action, and for most Test element content checks, it comes down to testing for a combination of a robust and unique selector and text value.

Text value

Picking a unique text value to test for is key for both the Test element content and Test document content check types. The need to pick unique text values does not apply to the Wait for element check type because the test doesn't test for text values.

When selecting the text for the check, make sure the text is a direct consequence of the previous action. For example:

  • After clicking a login button or logout link, you could test the subsequent page for the presence of an account name or the corresponding logout or login link.
  • After clicking on a link to go to a product page, test for product specifications or an add to cart button.
  • Look for a link on the new page that you need for the next step.

Do not pick text that shows up the same on every page. For example, do not use footer text. Footer text tells you nothing about the progression of the transaction.

Note: Use regular expressions where applicable. For example, if after performing a search action, your page reads "15 result(s) found," set a content check for .* result(s), found, and set the content check condition to matches regular expression (learn more).

After picking the text for your check, make sure you formulate a unique and robust (resistant to changes on the page) CSS or XPath selector. See the next section, Selectors.

Selectors

Picking a robust and solid selector is key for both Test element content and Wait for element test types. Since pointing at a specific element is not an option for the Test document content test type, this paragraph does not apply.

A good selector is unique on the page. Using a unique value allows you to be certain Uptrends is looking at the correct element. Where possible, use the element's id attribute, as these should generally be unique to that specific element. For example, //*[@id=’testId’] or #testId.

Caveats, pitfalls, and tips

Keep case sensitivity in mind. With the use of CSS, text can (and does regularly) appear as all caps on the page, while it uses sentence case in the DOM. That means the selector could read //span[text()='Hello'], but the text on the page could read "HELLO." The selector should reflect the information in the DOM, and the string you enter for matching should reflect what's actually on the page.

Some pages use dynamic IDs for their elements. For example, we could record a click on a span that shows up in the DOM as
<span id="example-12345">.
However, after a page reload, this exact same element would show up as
<span id="example-12789">.
Use XPath to handle dynamic IDs. For example,
//span[contains(@id,'example-')].