Selenium Tabs

A Python library that makes browser automation with Selenium more intuitive by providing a tab-centric interface. Manage multiple browser tabs with ease, perform common operations, and interact with web elements using a clean, Pythonic API.

And guess what! You don't need to manually download drivers for the browser—it's all taken care of by the library. Install and start right away.

Note: Local automated tests are designed for Chrome and run headless when Chrome is available.

🚀 Top Features

• Tab Management: Open, close, switch, and query tab state with ease.
• Element Selection: Use CSS selectors, jQuery, and PyQuery for powerful element querying.
• Page Interaction: Scroll, click, and wait for elements with robust error handling.
• Advanced Features: Direct driver access, task scheduling, and more.
• Automatic Driver Management: No need to manually download or manage browser drivers.

🔧 Installation

pip install seleniumtabs

For local development with uv:

git clone https://github.com/inquilabee/selenium-tabs.git
cd selenium-tabs
uv sync --all-groups

📋 Requirements

• Python 3.13+
• Chrome or Firefox browser

🛠️ Development

This project uses uv and PEP 621 package metadata in pyproject.toml.

make sync          # install runtime and development dependencies
make test          # run the default deterministic test suite
make integration   # run live browser/network tests
make check-commit  # run the fast local quality gate
make lint          # run all pre-commit hooks
make build         # build wheel and sdist

Default tests use local HTML fixtures from tests/fixtures/pages/ and exclude integration tests. Live-site tests are marked with @pytest.mark.integration because they require Chrome, network access, and external websites that may change.

Before publishing, configure PyPI Trusted Publishing for this GitHub repository, the publish workflow, and the pypi environment. Releases build with uv build and publish with uv publish from GitHub Actions.

🚀 Quick Start

from seleniumtabs import Browser

# Create a browser instance and open multiple tabs
with Browser(name="Chrome", implicit_wait=10) as browser:
    # Open multiple websites in different tabs
    google = browser.open("https://google.com")
    yahoo = browser.open("https://yahoo.com")

    # Work with tabs
    print(f"Current tab: {browser.current_tab}")
    print(f"First tab: {browser.first_tab}")
    print(f"Last tab: {browser.last_tab}")

    # Switch between tabs
    yahoo.switch()
    google.switch()

    # Close a tab
    yahoo.close()

✨ Key Features

1. Tab Management

with Browser(name="Chrome") as browser:
    # Open tabs
    tab1 = browser.open("https://example.com")
    tab2 = browser.open("https://example.org")

    # Access tab properties
    print(tab1.title)  # Page title
    print(tab1.url)    # Current URL
    print(tab1.domain) # Domain name

    # Check tab state
    print(tab1.is_active)  # Is this the active tab?
    print(tab1.is_alive)   # Is the tab still open?

2. Element Selection

with Browser(name="Chrome") as browser:
    tab = browser.open("https://example.com")

    # CSS Selectors
    elements = tab.css("div.class-name")
    for element in elements:
        print(element.text)

    # Chaining selectors
    main_content = tab.css("main")[0]
    links = main_content.css("a")

    # Get element attributes
    for link in links:
        print(link.get_attribute("href"))

3. Page Interaction

with Browser(name="Chrome") as browser:
    tab = browser.open("https://example.com")

    # Scrolling
    tab.scroll_down(times=3)  # Scroll down 3 times
    tab.scroll_up(times=2)    # Scroll up 2 times
    tab.scroll_to_bottom()    # Scroll to page bottom

    # Clicking elements
    element = tab.css("button")[0]
    tab.click(element)

    # Wait for elements
    tab.wait_for_presence("div", "class-name", wait=10)
    tab.wait_for_visibility("button", "submit", wait=5)

4. Advanced Features

with Browser(name="Chrome") as browser:
    tab = browser.open("https://example.com")

    # jQuery-like operations
    jq_elements = tab.jq("div.class-name")

    # PyQuery for HTML parsing
    pq = tab.pyquery
    text_content = pq.text()

    # Run JavaScript
    result = tab.run_js("return document.title")

    # Schedule tasks
    def refresh_page(tab):
        tab.refresh()

    tab.schedule_task(refresh_page, period=60)  # Refresh every 60 seconds

Direct Driver Access

• If a feature is not directly available in the Tab object, you can access the underlying Selenium WebDriver directly via tab.driver.

• Example:

  # Access driver methods directly
  tab.driver.execute_script("return document.title")
  

• Fallback Behavior: If you call a non-existent method on the Tab object, an attempt is made to query tab.driver.method_name via __getattribute__.

jQuery Integration

• You can use the tab.jq or tab.jquery property to run jQuery-like selectors and operations directly on the live browser DOM.
• Tested features:
  • Selecting elements with jQuery syntax.
  • Chaining jQuery selectors.
  • Accessing and manipulating attributes and text.
  • Interacting with elements (e.g., click, scroll).

Example:

jq_elements = tab.jq("div.class-name")
for el in jq_elements:
    print(el.text)

PyQuery Integration

• You can use the tab.pyquery or tab.pq property to parse and query the current page's HTML snapshot using PyQuery (lxml-based).
• Tested features:
  • .items() for iterating over selections and sub-selections.
  • .find(), .parent(), .children() for DOM navigation.
  • .attr(), .text(), .html() for attribute and content access.
  • Consistency between tab.pyquery and tab.pq.
  • Integration with real-world pages (e.g., Yahoo).

Example:

pq = tab.pyquery
for link in pq("nav a").items():
    print(link.attr("href"))
print(pq("title").text())

🔍 Browser Options

with Browser(
    name="Chrome",           # Browser name ("Chrome" or "FireFox")
    implicit_wait=10,        # Default wait time for elements
    headless=False,          # Run browser in headless mode
    full_screen=True,        # Start browser in full screen
    page_load_timeout=60     # Page load timeout in seconds
) as browser:
    # Your code here

✅ Tested Features

This library is thoroughly tested for:

• Tab Management: Opening, closing, switching, and querying tab state.
• Element Selection: CSS selector queries, chaining, and attribute access.
• Page Interaction: Scrolling, clicking, and waiting for elements.
• Page Loading: Full and partial page load handling, including timeouts.
• Tab Refresh: Full and partial refresh with robust error handling.
• Task Scheduling: Periodic tab actions (e.g., auto-refresh).
• Integration with jQuery and PyQuery (see below).

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.