Splinter

Common errors

• ModuleNotFoundError: No module named 'selenium'

  cause Splinter was installed without the necessary `selenium` dependency. Since v0.17.0, `selenium` is no longer installed by default.
  fix Install Splinter with the appropriate Selenium extra: `pip install splinter[selenium4]` (recommended) or `pip install splinter[selenium3]`.

• WebDriverException: Message: 'geckodriver' executable needs to be in PATH.

  cause The browser driver executable (e.g., `geckodriver` for Firefox, `chromedriver` for Chrome, `msedgedriver` for Edge) is not found in your system's PATH.
  fix Download the correct driver for your browser version and operating system, then either place it in a directory listed in your system's PATH, or provide its path explicitly during browser initialization. Alternatively, use `webdriver-manager` to automate this: `pip install webdriver-manager` and then `from webdriver_manager.chrome import ChromeDriverManager; driver_path = ChromeDriverManager().install()`.

• AttributeError: 'WebDriver' object has no attribute 'find_by_css' (or similar method)

  cause You might be attempting to call Splinter methods directly on the underlying `selenium.webdriver` object instead of the `splinter.Browser` instance, or you're using a method that doesn't exist in your installed Splinter version.
  fix Ensure you are using the `splinter.Browser` object (e.g., `browser.find_by_css(...)`) for Splinter's API. If the method still doesn't exist, check the official Splinter documentation for its availability in your version.

• selenium.common.exceptions.SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version XX

  cause There is a mismatch between the version of your Chrome browser and the version of ChromeDriver installed/used.
  fix Update your ChromeDriver executable to match your installed Chrome browser version. Using `webdriver_manager.chrome.ChromeDriverManager().install()` (or similar for other browsers) is the easiest way to keep drivers automatically updated.

Warnings

• breaking Python 2.7 support was removed. Splinter v0.17.0 and later only support Python 3.
  Fix: Ensure your project runs on Python 3.x.
• breaking Selenium 3 is no longer installed by default since v0.17.0. Users must explicitly install either `splinter[selenium3]` or `splinter[selenium4]` (recommended).
  Fix: Update your `pip install` command to include the desired Selenium extra, e.g., `pip install splinter[selenium4]`.
• deprecated The methods `WebDriver.is_element_not_visible_by_css` and `WebDriver.is_element_visible_by_css` were deprecated in favor of `WebDriverElement.is_visible()` and `WebDriverElement.is_not_visible()`.
  Fix: Replace calls to the deprecated methods with `element.is_visible()` or `element.is_not_visible()` on the `WebDriverElement` object.
• gotcha Calling `CookieManager.delete()` without any arguments now deletes *all* cookies. Prior to v0.19.0, its behavior when called without arguments might have been different or unclear.
  Fix: Be aware of the new default behavior. If you intend to delete specific cookies, ensure you pass the relevant arguments to `delete()`.
• gotcha Compatibility issues can arise from mismatched Splinter and Selenium versions. For example, Splinter v0.16.0 pinned Selenium < 4.0, while v0.17.0 added Selenium 4 support.
  Fix: Always install Splinter with the appropriate Selenium extra (`splinter[selenium3]` or `splinter[selenium4]`) and ensure your `selenium` package version is compatible with your Splinter version. If using `webdriver-manager`, ensure it's up to date.

Install

• pip install splinter Base installation
• pip install splinter[selenium4] With Selenium 4 support (recommended)
• pip install splinter[selenium3] With Selenium 3 support (for older projects)

Imports

• Browser

  from splinter import Browser

Quickstart

This quickstart demonstrates how to initialize a headless Chrome browser, navigate to a URL, fill out a login form, click a button, and assert text presence. It includes error handling and ensures the browser is closed properly. For Chrome/Firefox, ensure the respective driver (e.g., chromedriver, geckodriver) is in your system's PATH or managed by a tool like `webdriver-manager`.

from splinter import Browser
import os

# Optional: Use webdriver-manager to automatically download/manage drivers
# from webdriver_manager.chrome import ChromeDriverManager
# driver_path = ChromeDriverManager().install()

# Create a Browser instance
# Common options: 'chrome', 'firefox', 'edge'
# headless=True is recommended for CI/CD or background tasks
browser = Browser('chrome', headless=True) # Or 'firefox', 'edge', etc.

try:
    browser.visit('http://quotes.toscrape.com/login')

    print(f"Visiting: {browser.url}")
    browser.fill('username', 'admin')
    browser.fill('password', 'password')
    browser.find_by_css('input[type="submit"]').click()

    if browser.is_text_present('Logged in!'):
        print(f"Successfully logged in. Current URL: {browser.url}")
        browser.click_link_by_text('Logout')
        assert browser.is_text_present('Login')
        print("Successfully logged out.")
    else:
        print("Login failed.")

except Exception as e:
    print(f"An error occurred during the test: {e}")
finally:
    if browser:
        browser.quit() # Always close the browser