Testing

xlwings Lite has a built-in pytest runner. Write tests in the tests.py file, then click the green Run all tests button to run them all, or select a specific test in the dropdown. You can also click on ▶ Run test above any test function to run just that one.

Basic syntax

A test is a function whose name starts with test_. Use assert statements to check conditions:

def test_addition():
    assert 1 + 1 == 2

Importing your own code

Tests can import functions from main.py:

# main.py
from xlwings import func


@func
def hello(name: str):
    return f"Hello {name}!"

# tests.py
from main import hello


def test_hello():
    assert hello("xlwings") == "Hello xlwings!"

Async tests

Tests defined as async def are supported. However, they’re executed outside of pytest, so pytest fixtures, markers, and plugins aren’t supported.

import xlwings as xw


async def test_active_book():
    # Lazy API: doesn't load all values from the book
    book = await xw.books.get_active()
    values = await book.sheets[0]["A1:B2"].get_value()
    assert values == [[1, 2], [3, 4]]

Accessing the active workbook

Both the eager API (xw.books.active) and lazy API (await xw.books.get_active()) work in tests. The eager API fetches values for every sheet — for large workbooks, prefer await xw.books.get_active() from an async test, which loads on demand, see previous example.

Configuring pytest

Add a [tool.pytest.ini_options] section to pyproject.toml. For example:

[tool.pytest.ini_options]
addopts = "-s"  # show print() output from tests (remove to capture)

Restart xlwings Lite after changing pyproject.toml.

Note

  • Async tests don’t go through pytest, so options under [tool.pytest.ini_options] only affect sync tests.

  • [tool.pytest] is only supported with pytest 9.0+. xlwings Lite currently ships an older verison, so use [tool.pytest.ini_options] for now.

Limitations

  • Async pytest plugins like pytest-asyncio are not supported — xlwings Lite runs async tests outside of pytest instead.

  • Class-based tests are collected, but they only run via “Run all tests” and don’t appear in the dropdown or get ▶ Run test entries.

  • conftest.py is not supported. Put shared helpers in main.py (importable as main) instead.

  • Multiple test files are not supported. All tests live in tests.py.