Djanguard

Bullshit free Monitoring Solution.

Selenium Style Commands

DSLExecutor User Guide

Introduction to DOM Selection

To effectively interact with web elements using the DSL commands, you need to understand how to locate elements on a webpage. This process is called “DOM selection,” and it is based on using selectors that uniquely identify HTML elements in the Document Object Model (DOM). Below, we explain common types of selectors that are used throughout the examples.

Types of Selectors

Selectors are the key to targeting elements on a webpage for actions like clicking, filling out forms, or verifying text. Here are some of the main types of selectors:

  1. ID Selector (#id)
    • Example: #id_username
    • Usage: Selects an element with a specific ID. IDs are unique within the page, making them ideal for precise selection.
    • Example Command: fill "#id_username" with "my_username"
    • Explanation: This command fills an input field with the ID id_username with the value my_username.
  2. Class Selector (.class)
    • Example: .btn-primary
    • Usage: Selects elements by their class attribute. Classes are used to style elements and are often shared across multiple elements.
    • Example Command: click ".btn-primary"
    • Explanation: This command clicks on an element with the class btn-primary.
  3. Attribute Selector ([attribute=value])
    • Example: [type="checkbox"]
    • Usage: Selects elements based on an attribute and its value. Attribute selectors are useful for targeting elements like input fields or buttons based on their properties.
    • Example Command: click "input[type=\"checkbox\"]"
    • Explanation: This command clicks on an input element of type checkbox.
  4. Tag and Attribute Combination
    • Example: a[href="/search/"]
    • Usage: Targets an anchor (a) tag with a specific href attribute. This is helpful for selecting links.
    • Example Command: click "a.nav-link[href=\"/search/\"]"
    • Explanation: This command clicks on a link that navigates to the /search/ page.
  5. Class and Position Selector (:nth-of-type())
    • Example: .list-item:nth-of-type(2)
    • Usage: Selects an element based on its position among siblings with the same tag. This is helpful for targeting specific elements in a list.
    • Example Command: click ".list-item:nth-of-type(2)"
    • Explanation: This command clicks on the second element with the class list-item.
  6. Child Selector (>)
    • Example: div.container > button.btn-submit
    • Usage: Selects a direct child of an element. This is helpful for narrowing down elements that are directly within a parent.
    • Example Command: click "div.container > button.btn-submit"
    • Explanation: This command clicks on a button with the class btn-submit that is a direct child of a div with the class container.
  7. General Sibling Selector (+)
    • Example: label + input[type="text"]
    • Usage: Selects an element that is immediately preceded by a specified sibling. This is useful for selecting related form elements.
    • Example Command: click "label + input[type=\"text\"]"
    • Explanation: This command clicks on an input field that is immediately after a label.
  8. Attribute Starts-With Selector (^=)
    • Example: a[href^="https://example.com"]
    • Usage: Selects elements whose attribute value starts with a given string. This is helpful for targeting links with specific URLs.
    • Example Command: click "a[href^=\"https://example.com\"]"
    • Explanation: This command clicks on a link where the href attribute starts with https://example.com.
  9. Attribute Ends-With Selector ($=)
    • Example: img[src$=".png"]
    • Usage: Selects elements whose attribute value ends with a given string. This is useful for targeting images or other resources with specific file types.
    • Example Command: click "img[src$=\".png\"]"
    • Explanation: This command clicks on an image where the src attribute ends with .png.
  10. Attribute Contains Selector (*=)
    • Example: button[class*='-primary']
    • Usage: Selects elements whose attribute value contains a given substring. This is useful for selecting elements with partially matching attributes.
    • Example Command: click "button[class*='-primary']"
    • Explanation: This command clicks on a button whose class contains -primary.

How to Find the Right Selector

To effectively automate interactions with a webpage, it is crucial to use the correct selector to uniquely identify elements. Here are some tips:

  • Inspect the Webpage: Use your browser’s Developer Tools (usually accessible via right-click -> “Inspect”) to explore the HTML structure of the webpage.
  • ID as the First Choice: If an element has an id, use it, as IDs are unique within the page, ensuring precise targeting.
  • Use Classes for Shared Elements: If multiple elements share the same style or behavior, classes are helpful. Be aware that classes may be used on multiple elements.
  • Attribute Selectors for Specific Attributes: When elements do not have unique IDs or classes, use attribute selectors to target them by attributes like type, name, or placeholder.
  • Combination Selectors for Precision: Use a combination of tag names, classes, and attributes to create precise selectors when needed.

Standards for Selectors

Selectors are based on the CSS (Cascading Style Sheets) selector syntax, which is a web standard defined by the World Wide Web Consortium (W3C). CSS selectors are not only used for styling purposes but also for selecting elements in JavaScript and automation frameworks like Playwright. The syntax and behavior of these selectors follow the rules set by the CSS Selectors Level 3 specification.

Commands Overview

The DSL commands allow you to perform actions like filling forms, clicking buttons, and verifying content on a webpage. Below are examples of how to use each command.

1. Fill an Input Field

Command:

fill "#id_username" with "my_username"

Explanation: This command fills the input field with the selector #id_username with the value my_username.

Command:

click ".btn-primary"

Explanation: This command clicks on an element with the class .btn-primary. This is commonly used for buttons or links.

3. Check Text Presence

Command:

check-text "Welcome to the dashboard" is-present

Explanation: This command checks if the text “Welcome to the dashboard” is present on the current page. If the text is not found, an error will be logged.

4. Assert Element Visibility

Command:

assert element present "#logout-button"

Explanation: This command verifies that the element with the selector #logout-button is present on the page.

5. Retrieve Element Content

Command:

get element content "table.table.table-striped"

Explanation: This command gets the inner content of the table with the class table.table-striped. This is useful for capturing results or output from the webpage.

Command:

click "a.nav-link[href=\"/search/\"]"

Explanation: This command clicks on a link that navigates to the search page. The selector targets an anchor tag with the class nav-link and an href attribute of /search/.

7. Fill in a Text Area

Command:

fill "textarea.form-control.mb-3[name=\"query\"]" with "John Doe"

Explanation: This command fills a text area with the name query with the value “John Doe”. Text areas are often used for larger inputs like comments or queries.

8. Submit a Form

Command:

click "button.btn.btn-primary.my-2.my-sm-0[type=\"submit\"]"

Explanation: This command clicks a button that submits a form. The selector targets a button with multiple classes and a type of submit.

9. Verify Search Results

Command:

check-text "Result" is-present

Explanation: This command verifies that the text “Result” is present on the page, indicating that the search results are displayed.

10. Capture Table Content

Command:

get element content "table.table.table-striped"

Explanation: This command captures the content of a table with the class table.table-striped. This is useful for logging data from the webpage, such as search results or reports.

11. Click Using an ID Selector

Command:

click "#submit-button"

Explanation: This command clicks on an element with the ID #submit-button. IDs are unique within the page, making this a precise way to target an element.

12. Click Using an Attribute Selector

Command:

click "input[type=\"checkbox\"]"

Explanation: This command clicks on an input element of type checkbox. Attribute selectors are useful for targeting elements with specific attributes.

13. Fill Using a Placeholder Selector

Command:

fill "input[placeholder=\"Enter your name\"]" with "Jane Doe"

Explanation: This command fills an input field that has a placeholder text of “Enter your name” with the value “Jane Doe”. Placeholder attributes are commonly used for guiding users.

14. Click Using a Class and Position Selector

Command:

click ".list-item:nth-of-type(2)"

Explanation: This command clicks on the second element with the class list-item. Position selectors like :nth-of-type() help in selecting elements based on their order.

15. Check Text Within a Specific Element

Command:

check-text "Error" is-present in "div.alert-danger"

Explanation: This command checks if the text “Error” is present within a specific element with the selector div.alert-danger. This is useful when the text needs to be verified within a certain context.

16. Assert Element Using Multiple Classes

Command:

assert element present "div.card.card-info"

Explanation: This command asserts the presence of a div element with multiple classes card and card-info. This is helpful for targeting elements that share multiple styles or categories.

17. Retrieve Content Using Attribute and Class Selector

Command:

get element content "div[data-status=\"active\"].user-info"

Explanation: This command gets the content of a div element with the attribute data-status="active" and the class user-info. This helps in targeting specific elements dynamically generated or filtered by status.

18. Click Using a Child Selector

Command:

click "div.container > button.btn-submit"

Explanation: This command clicks on a button with the class btn-submit that is a direct child of a div element with the class container. Child selectors help in targeting elements within a specific parent.

19. Click Using a General Sibling Selector

Command:

click "label + input[type=\"text\"]"

Explanation: This command clicks on an input element of type text that is immediately after a label element. The + selector is useful for selecting siblings that are adjacent.

20. Click Using an Attribute Starts-With Selector

Command:

click "a[href^=\"https://example.com\"]"

Explanation: This command clicks on an anchor tag (a) where the href attribute starts with https://example.com. The ^= selector is useful for partial matches at the beginning of an attribute value.

21. Click Using an Attribute Ends-With Selector

Command:

click "img[src$=\".png\"]"

Explanation: This command clicks on an img element where the src attribute ends with .png. The $= selector is used for matching elements with attributes that end with a certain value.

22. Click Using an Attribute Contains Selector

Command:

click "button[class*='-primary']"

Explanation: This command clicks on a button element where the class attribute contains -primary. The *= selector is useful for matching elements with an attribute that contains a specific substring.

23. Fill Input Field Using a Complex Selector

Command:

fill "form#login-form input[name=\"username\"]" with "admin"

Explanation: This command fills the input field named username inside a form with the ID login-form with the value admin. Complex selectors allow for precise targeting of elements in nested structures.

24. Assert Presence of Element Using Pseudo-Class

Command:

assert element present "ul > li:first-child"

Explanation: This command asserts that the first li element within a ul list is present. Pseudo-classes like :first-child are useful for targeting specific positions within a group of elements.

25. Click Using Descendant Selector

Command:

click "div.container button.btn-success"

Explanation: This command clicks a button with the class btn-success that is a descendant of a div element with the class container. The descendant selector allows for targeting elements within a hierarchy.

More examples

DSLExecutor Command Examples

Below are multiple examples for each command. These examples show different use cases of each command, using various selectors and scenarios to illustrate their versatility.

Fill Command Examples

  1. fill "#first_name" with "John"
  2. fill "input[placeholder='Enter email']" with "john@example.com"
  3. fill "input[type='password']" with "mySecurePassword"
  4. fill "textarea.comment-box" with "This is my comment."
  5. fill "#user_address" with "123 Main St."
  6. fill "input[name='zip_code']" with "90210"
  7. fill "input[data-id='username']" with "uniqueUser123"
  8. fill "form#signup-form input[name='phone']" with "123-456-7890"
  9. fill "input.contact-field" with "contact@example.com"
  10. fill "textarea[rows='5']" with "This is a multiline text input."

Click Command Examples

  1. click "button[type='submit']"
  2. click ".btn.btn-primary"
  3. click "#logout"
  4. click "div.alert > a.close"
  5. click "a[href='/profile']"
  6. click "li.menu-item:nth-of-type(3)"
  7. click "span.icon-refresh"
  8. click "input[type='checkbox']"
  9. click "#save-button"
  10. click "nav.main-menu a[href='/settings']"

Check Text Command Examples

  1. check-text "Login successful" is-present
  2. check-text "User not found" is-present
  3. check-text "Welcome, John!" is-present
  4. check-text "Payment completed" is-present
  5. check-text "Error: invalid credentials" is-present
  6. check-text "Your cart is empty" is-present
  7. check-text "Profile updated successfully" is-present
  8. check-text "Terms and Conditions" is-present
  9. check-text "404 - Page Not Found" is-present
  10. check-text "Subscription confirmed" is-present

Assert Element Present Command Examples

  1. assert element present "#profile-picture"
  2. assert element present "div.container"
  3. assert element present "input[type='submit']"
  4. assert element present "ul > li:first-child"
  5. assert element present "div#footer .social-links"
  6. assert element present "form.contact-form"
  7. assert element present "nav .menu-item.active"
  8. assert element present "button[disabled]"
  9. assert element present "header > h1.site-title"
  10. assert element present "div.modal[role='dialog']"

Get Element Content Command Examples

  1. get element content "table.data-table"
  2. get element content "div#main-content"
  3. get element content "span.price-tag"
  4. get element content "p.description-text"
  5. get element content "h1.page-title"
  6. get element content "ul.list-items > li:nth-child(2)"
  7. get element content "section#about-us"
  8. get element content "a[href='/contact']"
  9. get element content "footer .address"
  10. get element content "div.alert-message"

Click Using Attribute Selector Command Examples

  1. click "a[data-toggle='dropdown']"
  2. click "input[aria-label='Search']"
  3. click "button[title='Save Changes']"
  4. click "div[role='alert']"
  5. click "li[data-active='true']"
  6. click "img[alt='Product Image']"
  7. click "button[aria-expanded='false']"
  8. click "input[required]"
  9. click "select[name='country']"
  10. click "a[target='_blank']"

Fill Using Placeholder Selector Command Examples

  1. fill "input[placeholder='Full Name']" with "Jane Doe"
  2. fill "input[placeholder='Enter your password']" with "safePassword123"
  3. fill "textarea[placeholder='Leave your comment here']" with "Great product!"
  4. fill "input[placeholder='Search']" with "Django tutorials"
  5. fill "input[placeholder='Email address']" with "jane@example.com"
  6. fill "input[placeholder='Phone Number']" with "1234567890"
  7. fill "textarea[placeholder='Describe your issue']" with "The app crashes on login."
  8. fill "input[placeholder='Username']" with "jane_doe"
  9. fill "input[placeholder='ZIP code']" with "12345"
  10. fill "input[placeholder='Confirm Password']" with "safePassword123"

Click Using Child Selector Command Examples

  1. click "div.container > button.submit"
  2. click "ul.list > li.item:first-child"
  3. click "div.card > a.read-more"
  4. click "form#signup-form > input[type='text']"
  5. click "section.news > article:first-child"
  6. click "nav.menu > ul > li:nth-child(2)"
  7. click "div.panel > button.toggle"
  8. click "div.wrapper > a.link"
  9. click "header > nav > ul > li:last-child"
  10. click "div.row > div.col-md-6 > button.buy-now"