Optional Settings File User Customization

[GCuser99]

I'm contemplating adding functionality for customizing SeleniumVBA settings prior to run-time such as where to locate drivers, pre-loading capabilities from file, auto-driver-updating parameters, etc.

Principle design objectives:

1. Use very flexible and easy to maintain INI file format
2. Completely optional - no requirement over and above current usage state

My current draft approach is to create a file called SeleniumVBA.ini in the same folder as the SeleniumVBA add-in. At object initialization, read the relevant INI entries to initialize global variables. If the INI file does not exist, or the entries do not exist in the file, then fall back on the current SeleniumVBA "system" defaults.

Here is a draft version of what the SeleniumVBA.ini file might contain:

# This settings file is completely optional. For it to have effect,
# it must be located in the same folder as the SeleniumVBA code library.
 
# If a value for an entry is not specified, then the system
# default value will be used.
 
# Note that all path-type entry values recognize the %[Environ]% syntax.
 
[GENERAL]
 
# The driver_location_folder system defaults to Downloads folder.
# The default_io_folder system defaults to the active vba project's
# document location - leave this blank to use default.
# Valid values for command_window_style are vbHide (default), 
# vbNormalFocus, vbMinimizedFocus, vbMaximizedFocus, vbNormalNoFocus,
# and vbMinimizedNoFocus.
 
driver_location_folder=%USERPROFILE%\Downloads
default_io_folder=
command_window_style=vbHide
 
[AUTO-DRIVER-UPDATE]
 
# If auto_detect_and_update=True (system default) then everytime
# the WebDriver's Start* method is called, the Selenium driver's
# version is checked against the corresponding browser version.
# If the driver is not compatible with browser, it will be updated.
# min_compatibility_level determines trigger for updating an
# an out-of-date driver. System default is svbaBuildMajor.
# Use svbaMinor for less frequent updating, and svbaExactMatch
# for more frequent updating.
 
auto_detect_and_update=True
min_compatibility_level=svbaBuildMajor
 
# Below are browser-specific initializations.
# To automatically initialize a set of capabilities each time the
# OpenBrowser method of WebDriver class is invoked, set the
# preload_capabilities_file_path entry to the path of a valid json
# capabilities file. Note that if preload_capabilities_file_path is
# set to a blank value, or the entry is missing or commented out,
# then this option is ignored. Use the SaveToFile method of the
# WebCapabilities class to save a default set of capabilities
# for pre-loading.
 
[CHROME]
 
preload_capabilities_file_path=
 
[EDGE]
 
preload_capabilities_file_path=
 
[FIREFOX]
 
preload_capabilities_file_path=
 
[INTERNET EXPLORER]
 
preload_capabilities_file_path=
 
[PDF_DEFAULT_PRINT_SETTINGS]
 
# Valid units values are svbaInches (default) or svbaCentimeters.
# Valid orientation values are svbaPortrait (default) or svbaLandscape.
 
units=svbaInches
page_height=11
page_width=8.5
margin_bottom=.393701
margin_top=.393701
margin_right=.393701
margin_left=.393701
background=False
orientation=svbaPortrait
print_scale=1.0
shrink_to_fit=True

As far as implementation goes, I've been experimenting with the following api technique for reading from the INI file:

Private Declare PtrSafe Function GetPrivateProfileString Lib "kernel32" Alias "GetPrivateProfileStringA" (ByVal lpApplicationName As String, ByVal lpKeyName As Any, ByVal lpDefault As String, ByVal lpReturnedString As String, ByVal nSize As Long, ByVal lpFilename As String) As Long

Public Function ReadIniFileEntry(ByVal filePath As String, ByVal section As String, ByVal keyName As String, Optional ByVal defaultValue As Variant = vbNullString) As String
    'reads a single settings file entry
    Const lenStr = 255
    Dim outputLen As Long
    Dim retStr As String * lenStr
    Dim fso As New FileSystemObject
    
    'check if optional settings file exists - if not then use default and exit
    If Not fso.FileExists(filePath) Then
        ReadIniFileEntry = defaultValue
        Exit Function
    End If
    
    'try to read and return the section/keyName value - if not then use default and exit
    retStr = Space(lenStr)
    outputLen = GetPrivateProfileString(section, keyName, vbNullString, retStr, lenStr, filePath)
    If outputLen Then
        ReadIniFileEntry = Left$(retStr, outputLen)
    Else
        ReadIniFileEntry = defaultValue
    End If
End Function

In the Class_Initialize Sub(s), the above would be called like below, where the last parameter of ReadIniFileEntry is the system default value:

Me.DefaultDriverFolder = ReadIniFileEntry(iniFilePath, "GENERAL", "driver_location_folder", oShell.Namespace("shell:Downloads").Self.Path)

Some of the nice properties of the api approach above are that it is random access - can read from the file only the entries that are needed when they are needed in SeleniumVBA without consuming the entire file, entries are order independent, case insensitivity of key/entry values, and very forgiving - if an entry key is misspelled, or a value is left blank, the approach will not throw an error - just returns null, which is then replaced with the default.

The SeleniumVBA.ini file could either be copied from the GitHub distribution folder, and/or created via a method of the WebDriver class, such as this easy to maintain method below:

'@Description("Creates a (optional) settings file with default settings")
Public Sub CreateSettingsFile()
    Dim filePath As String
    Dim fso As New FileSystemObject
    Dim ts As TextStream
    Dim overWriteFile As Long
    Dim i As Long
    
    filePath = GetFullLocalPath(ThisWorkbook.Path) & "\SeleniumVBA.ini"
    
    'if settings file already exists, then warn user
    If fso.FileExists(filePath) Then
        overWriteFile = MsgBox("A SeleniumVBA settings file already exists at:" & vbCrLf & vbCrLf & filePath & vbCrLf & vbCrLf & "Would you like to replace it?", vbYesNo, "SeleniumVBA")
        If overWriteFile = vbNo Then Exit Sub
    End If
    
    Dim entryCol As New Collection
    
    entryCol.Add "# Note: if value for an entry is not specified, then system default"
    entryCol.Add "# value will be used."
    entryCol.Add " "
    entryCol.Add "# Note: all path-type entries below recognize the %[Environ]% syntax."
    entryCol.Add " "
    
    entryCol.Add "[GENERAL]"
    entryCol.Add " "
    entryCol.Add "# driver_location_folder system defaults to Downloads folder."
    entryCol.Add "# default_io_folder system defaults to the active vba project's"
    entryCol.Add "# document location - leave this blank to use default."
    entryCol.Add " "
    entryCol.Add "driver_location_folder=%USERPROFILE%\Downloads"
    entryCol.Add "default_io_folder="
    entryCol.Add "command_window_style=vbHide"
    entryCol.Add " "
    
    entryCol.Add "[AUTO-DRIVER-UPDATE]"
    entryCol.Add " "
    entryCol.Add "# If auto_detect_and_update=True (system default) then everytime"
    entryCol.Add "# the WebDriver's Start* method is called, the Selenium driver's"
    entryCol.Add "# version is checked against the corresponding browser version."
    entryCol.Add "# If the driver is not compatible with browser, it will be updated."
    entryCol.Add "# min_compatibility_level determines trigger for updating an"
    entryCol.Add "# an out-of-date driver. System default is svbaBuildMajor."
    entryCol.Add "# Use svbaMinor for less frequent updating, and svbaExactMatch"
    entryCol.Add "# for more frequent updating."
    entryCol.Add " "
    entryCol.Add "auto_detect_and_update=True"
    entryCol.Add "min_compatibility_level=svbaBuildMajor"
    entryCol.Add " "
    
    entryCol.Add "# Below are browser-specific initializations."
    entryCol.Add "# Set preload_capabilities_file_path to a json capabilities file path"
    entryCol.Add "# to automatically initialize a set of capabilities each time that the"
    entryCol.Add "# OpenBrowser method of WebDriver class is invoked. Note that if"
    entryCol.Add "# preload_capabilities_file_path is set to a blank value, invalid,"
    entryCol.Add "# or the entry is missing or commented out, then this option is ignored."
    entryCol.Add " "
    
    entryCol.Add "[CHROME]"
    entryCol.Add " "
    entryCol.Add "preload_capabilities_file_path="
    entryCol.Add " "

    entryCol.Add "[EDGE]"
    entryCol.Add " "
    entryCol.Add "preload_capabilities_file_path="
    entryCol.Add " "
    
    entryCol.Add "[FIREFOX]"
    entryCol.Add " "
    entryCol.Add "preload_capabilities_file_path="
    entryCol.Add " "
    
    entryCol.Add "[INTERNET EXPLORER]"
    entryCol.Add " "
    entryCol.Add "preload_capabilities_file_path="
    entryCol.Add " "
    
    entryCol.Add "[PDF_DEFAULT_PRINT_SETTINGS]"
    entryCol.Add " "
    entryCol.Add "# Valid units values are svbaInches (default) or svbaCentimeters."
    entryCol.Add "# Valid orientation values are svbaPortrait (default) or svbaLandscape."
    entryCol.Add " "
    entryCol.Add "units=svbaInches"
    entryCol.Add "page_height=11"
    entryCol.Add "page_width=8.5"
    entryCol.Add "margin_bottom=.393701"
    entryCol.Add "margin_top=.393701"
    entryCol.Add "margin_right=.393701"
    entryCol.Add "margin_left=.393701"
    entryCol.Add "background=False"
    entryCol.Add "orientation=svbaPortrait"
    entryCol.Add "print_scale=1.0"
    entryCol.Add "shrink_to_fit=True"
    
    Set ts = fso.CreateTextFile(filePath, True)
    
    For i = 1 To entryCol.Count
        ts.WriteLine entryCol.Item(i)
    Next i
    
    ts.Close
End Sub

The implementation outlined above requires several minor changes elsewhere, but in no way would affect the current functionality - only optionally extend it. I've had to add support for the %Environ% syntax in GetFullLocalPath, and refactor OpenBrowser to auto-load capabilities json files if specified in the settings, as below.

'@Description("Opens browser instance with specified capabilities")
Public Sub OpenBrowser(Optional caps As WebCapabilities, Optional ByVal invisible As Boolean = False, Optional ByVal incognito As Boolean = False, Optional capabilitiesFilePath As String = vbNullString)
    Dim resp As Dictionary
    
    If sessionId_ <> vbNullString Then
        Err.raise 1, "WebDriver", "Only one OpenBrowser command per WebDriver instance is allowed! Use CloseBrowser before another OpenBrowser to fix this."
    End If
    
    If caps Is Nothing Then
        Set caps = CreateCapabilities
        If capabilitiesFilePath <> vbNullString Then
            caps.LoadFromFile capabilitiesFilePath
        Else
            Select Case browser_
            Case svbaBrowser.Chrome
                If preloadChromeCapabilitiesFilePath <> vbNullString Then caps.LoadFromFile preloadChromeCapabilitiesFilePath
            Case svbaBrowser.Edge
                If preloadEdgeCapabilitiesFilePath <> vbNullString Then caps.LoadFromFile preloadEdgeCapabilitiesFilePath
            Case svbaBrowser.Firefox
                If preloadFirefoxCapabilitiesFilePath <> vbNullString Then caps.LoadFromFile preloadFirefoxCapabilitiesFilePath
            Case svbaBrowser.IE
                If preloadIECapabilitiesFilePath <> vbNullString Then caps.LoadFromFile preloadIECapabilitiesFilePath
            End Select
        End If
    End If
    
    If invisible Then
        caps.RunInvisible
    End If
    
    If incognito Then
        caps.RunIncognito
    End If
    
    Set resp = Execute(tCMD.CMD_NEW_SESSION, params("capabilities", caps.Dictionary))("value")
    
    sessionId_ = resp("sessionId")
End Sub

Anyway, reaching out for community feedback before taking any action, while continuing testing. Let me know your thoughts!

[6DiegoDiego9]

Thanks for continually improving SeleniumVBA, it's getting hotter and hotter :)

About this addition, I personally currently don't need it because I'm fine with current factory settings as default settings. Anyway, I have no comments to make except maybe on the clarity of the calling lines:

Me.DefaultDriverFolder = ReadIniFileEntry(iniFilePath, "GENERAL", "driver_location_folder", oShell.Namespace("shell:Downloads").Self.Path)

If I hadn't read your explanation and the content of the function, I wouldn't have understood that the Ini file is optional and that oShell.Namespace("shell:Downloads").Self.Path is the default returning value when the particular entry or even the whole Ini file doesn't exist.

However, I can't think of a better solution, so I'll get over it :)