Skip to content

A Selenium-WebDriver-based browser automation framework implemented for VBA.

License

Notifications You must be signed in to change notification settings

er-ri/selenium-wrapper-vba

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

15 Commits
 
 
 
 
 
 
 
 

Repository files navigation

SeleniumWrapperVBA

A Selenium-WebDriver-based browser automation framework implemented for VBA.

Table of Contents
  1. About The Project
  2. Requirements
  3. Getting Started
  4. Usage
  • Roadmap
  • License
  • Contribution
  • References
  • About The Project

    The project implements the endpoint node command defined in W3C WebDriver specification through VBA. You can use the project to do browser automation without installing a programming language such as Python, Java, etc. An MS office app and a browser-specific driver are required.

    Requirements

    1. MS Office(Excel, Word, PowerPoint, etc) 32bit or 64bit
    2. Browser's driver(Supported Browsers: Firefox, Chrome, Edge and Internet Explorer)

    Getting Started

    1. Download the browser-specific drivers, firefox, chrome, edge, or ie.
    2. In the office, by clicking the Developer tab(if you enabled) or through the shortcut key Alt + F11 to open the VBA Editor, and then import WebDriverOptions.cls, WebDriver.cls, WebElement.cls and JsonConverter.bas into your project. (File > Import File)
      • where JsonConverter.bas, a JSON Parser for VBA created and maintained by @timhall. For more details, see here.
    3. Include a reference to "Microsoft Scripting Runtime". (Tools > References Check "Microsoft Scripting Runtime")

    Note

    • Add browser's driver in the system PATH, or you can also specify the path when launching the corresponding browser's driver.
    • Some configurations are required before using iedriver, see here for more details about the configurations.

    Example

    Sub Example()
        Dim driver As New WebDriver
    
        driver.Chrome "to/your/path/chromedriver.exe"
        driver.OpenBrowser
        driver.NavigateTo "https://www.python.org/"
        driver.MaximizeWindow
        driver.FindElement(By.ID, "id-search-field").SendKeys "machine learning"
        driver.FindElement(By.ID, "submit").Click
        driver.TakeScreenshot ThisWorkbook.path + "./screenshot.png"
        driver.MinimizeWindow
        driver.CloseBrowser
        
        driver.Quit
        Set driver = Nothing
    End Sub

    Usage

    Element Retrieval

    Find Element

        ' Locator Strategies:
        Dim e1, e2, e3, e4, e5, e6, e7, e8 As WebElement
        set e1 = driver.FindElement(By.ID, "id")
        set e2 = driver.FindElement(By.ClassName, "blue")
        set e3 = driver.FindElement(By.Name, "name")
        set e4 = driver.FindElement(By.LinkText, "www.google.com")
        set e5 = driver.FindElement(By.PartialLinkText, "www.googl")
        set e6 = driver.FindElement(By.TagName, "div")
        set e7 = driver.FindElement(By.XPath, "/html/body/div[1]/div[3]")
        set e8 = driver.FindElement(By.CSS, ".search input[type='text']")

    Find Elements

        Dim elements() As WebElement
        elements = driver.FindElements(By.TagName, "a")
        
        Dim element As Variant
        For Each element In elements
            ' Do your stuff
        Next element

    Find Element From Element

        Dim elementRoot As WebElement
        Set elementRoot = driver.FindElement(By.ID, "root1")
        Dim elementChild As WebElement
        Set elementChild = driver.FindElementFromElement(elmentRoot, By.TagName, "div")

    Find Elements From Element

        Dim elementRoot As WebElement
        Set elementRoot = driver.FindElement(By.ID, "root1")
        Dim elementChildren() As WebElement
        elementChildren() = driver.FindElementsFromElement(elmentRoot, By.TagName, "p")

    Find Element From ShadowRoot

        Dim element as WebElement
        Dim elementShadowRoot As WebElement
        Set elementShadowRoot = driver.FindElement(By.ID, "shadow_id").GetShadowRoot()
        Set element = driver.FindElementFromShadowRoot(eleShadowRoot, By.CSS, "#shadow_css")

    Find Elements From ShadowRoot

        Dim elements() As WebElement
        Dim elementShadowRoot As WebElement
        Set elementShadowRoot = driver.FindElement(By.ID, "shadow_id").GetShadowRoot()
        elements() = driver.FindElementsFromShadowRoot(elementShadowRoot, By.CSS, "#shadow_css")

    Timeouts

    Get Timeouts

        Dim timeoutsDict As Dictionary
        Set timeoutsDict = driver.GetTimeouts()
        Debug.Print timeoutsDict("script")    ' 30000
        Debug.Print timeoutsDict("pageLoad")  ' 300000
        Debug.Print timeoutsDict("implicit")  ' 0

    Set Timeouts

        ' Set "script":40000,"pageLoad":500000,"implicit":15000
        driver.SetTimeouts 40000, 500000, 15000
    • Invoke the function before OpenBrowser.

    Working with iframe

        Set iframe1 = driver.FindElement(By.ID, "iframe1")
        driver.SwitchToFrame iframe1
        ' Perform some operations...
        driver.SwitchToParentFrame    ' switch back

    Working with multiple windows

        ' Get current windows's handle.
        Dim hWnd As String
        hWnd = driver.GetWindowHandle
        ' Get the handles of all the windows.
        Dim hWnds As New Collection
        Set hWnds = driver.GetWindowHandles
        ' Switch to another window.
        driver.SwitchToWindow (driver.GetWindowHandles(2))

    Execute JavaScript

        ' No parameters, no return value.
        driver.ExecuteScript "alert('Hello world!');"
        driver.DismissAlert
        ' Accept parameters, no return value.
        driver.ExecuteScript "alert('Proof: ' + arguments[0] + arguments[1]);", "1+1=", 2
        driver.DismissAlert
        ' Accept parameters, return the result. 
        Dim result As Long
        result = driver.ExecuteScript("let result = arguments[0] + arguments[1];return result;", 1, 2)
        Debug.Print result  ' 3

    Execute Async JavaScript

        ' No parameters, no return value.
        driver.ExecuteAsyncScript "alert('Hello world!');"
        driver.WaitUntilAlertIsPresent
        driver.DismissAlert
        ' Accept parameters, no return value.
        driver.ExecuteAsyncScript "alert('Proof: ' + arguments[0] + arguments[1]);", "1+1=", 2
        driver.WaitUntilAlertIsPresent
        driver.DismissAlert
        ' Accept parameters, return the result. 
        Dim result As Long
        result = driver.ExecuteAsyncScript("let result = arguments[0] + arguments[1];return result;", 1, 2)
        Debug.Print result  ' 3

    Working with alerts

        driver.WaitUntilAlertIsPresent
        driver.DismissAlert
    
        driver.ExecuteScript "prompt('question?')"
        driver.SendAlertText "answer"
        driver.AcceptAlert

    Screenshot

    Take Screenshot

        ' Take the current webpage screenshot and save it to the specific path.
        driver.TakeScreenshot ThisWorkbook.path + "./1.png"

    Take Element Screenshot

        ' Take the element screenshot directly.
        driver.FindElement(By.ID, "selenium_logo").TakeScreenshot ThisWorkbook.path + "./logo.png"
        ' or
        Dim seleniumLogo As WebElement
        Set seleniumLogo = driver.FindElement(By.ID, "selenium_logo")
        seleniumLogo.TakeScreenshot ThisWorkbook.path + "./logo.png"

    Enable Edge IE-mode

        Dim driver As New WebDriver
        Dim ieOptions As New WebDriverOptions
        ieOptions.BrowserType = InternetExplorer
        ieOptions.IntroduceFlakinessByIgnoringSecurityDomains = True    ' Optional
        ieOptions.IgnoreZoomSetting = True  ' Optional
        ieOptions.AttachToEdgeChrome = True
        ieOptions.EdgeExecutablePath = "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
        
        driver.InternetExplorer "C:\WebDriver\IEDriverServer_Win32_4.0.0\IEDriverServer.exe"
        driver.OpenBrowser ieOptions

    Headless mode

    Start Chrome in headless mode

        Dim driver As New WebDriver
        Dim chromeOptions As New WebDriverOptions
        chromeOptions.BrowserType = Chrome
        chromeOptions.ChromeArguments.add "--headless"
    
        driver.Chrome "C:\WebDriver\chromedriver_win32\chromedriver.exe"
        driver.OpenBrowser chromeOptions

    Start Firefox in headless mode

        Dim driver As New WebDriver
        Dim firefoxOptions As New WebDriverOptions
        firefoxOptions.BrowserType = Firefox
        firefoxOptions.FirefoxArguments.Add "-headless"
    
        driver.Firefox "C:\WebDriver\Firefox\geckodriver.exe"
        driver.OpenBrowser firefoxOptions

    Customize User-Agent

    Customize User-Agent in Chrome

        Dim driver As New WebDriver
        Dim chromeOptions As New WebDriverOptions
        
        driver.Chrome
        chromeOptions.BrowserType = Chrome
        chromeOptions.ChromeArguments.Add "--user-agent=my customized user-agent"
        driver.OpenBrowser chromeOptions
        driver.NavigateTo "https://www.whatismybrowser.com/detect/what-is-my-user-agent/"

    Roadmap

    Endpoint Node Command Function Name Element Function Name
    New Session OpenBrowser
    Delete Session CloseBrowser
    Status GetStatus
    Get Timeouts GetTimeouts
    Set Timeouts SetTimeouts
    Navigate To NavigateTo
    Get Current URL GetCurrentURL
    Back Back
    Forward Forward
    Refresh Refresh
    Get Title GetTitle
    Get Window Handle GetWindowHandle
    Close Window CloseWindow
    Switch To Window SwitchToWindow
    Get Window Handles GetWindowHandles
    New Window NewWindow
    Switch To Frame SwitchToFrame
    Switch To Parent Frame SwitchToParentFrame
    Get Window Rect GetWindowRect
    Set Window Rect SetWindowRect
    Maximize Window MaximizeWindow
    Minimize Window MinimizeWindow
    Fullscreen Window FullscreenWindow
    Get Active Element Not yet
    Get Element Shadow Root Not yet
    Find Element FindElement
    Find Elements FindElements
    Find Element From Element FindElementFromElement FindElement
    Find Elements From Element FindElementsFromElement FindElements
    Find Element From Shadow Root FindElementFromShadowRoot
    Find Elements From Shadow Root FindElementsFromShadowRoot
    Get Element Shadow Root GetElementShadowRoot GetShadowRoot
    Is Element Selected Not yet
    Get Element Attribute GetElementAttribute GetAttribute
    Get Element Property GetElementProperty GetProperty
    Get Element CSS Value Not yet
    Get Element Text GetElementText GetText
    Get Element Tag Name Not yet
    Get Element Rect Not yet
    Is Element Enabled Not yet
    Get Computed Role Not yet
    Get Computed Label Not yet
    Element Click ElementClick Click
    Element Clear ElementClear Clear
    Element Send Keys ElementSendKeys SendKeys
    Get Page Source GetPageSource
    Execute Script ExecuteScript
    Execute Async Script ExecuteAsyncScript
    Get All Cookies Not yet
    Get Named Cookie Not yet
    Add Cookie Not yet
    Delete Cookie Not yet
    Delete All Cookies Not yet
    Perform Actions Not yet
    Release Actions Not yet
    Dismiss Alert DismissAlert
    Accept Alert AcceptAlert
    Get Alert Text GetAlertText
    Send Alert Text SendAlertText
    Take Screenshot TakeScreenshot
    Take Element Screenshot TakeElementScreenshot TakeScreenshot
    Print Page Not yet
    • Browser Capabilities are not listed above.
    • Key action(Such as Enter, Shift, Control) has not been implemented.

    License

    Distributed under the MIT License. See LICENSE.txt for more information.

    Contribution

    Any suggestions for improvement or contribution to this project are appreciated! Creating an issue or pull request!

    References

    1. W3C WebDriver Working Draft:
    2. The Selenium Browser Automation Project
    3. The W3C WebDriver Spec, A Simplified Guide:
    4. geckodriver, WebDriver Reference
    5. Capabilities & ChromeOptions
    6. Capabilities and EdgeOptions

    About

    A Selenium-WebDriver-based browser automation framework implemented for VBA.

    Topics

    Resources

    License

    Stars

    Watchers

    Forks

    Releases

    No releases published

    Packages

    No packages published

    Contributors 3

    •  
    •  
    •  

    Languages