# Seldom: a unittest based framework for web, app and API automation

> Seldom wraps unittest in a testing framework that covers browser UI, mobile app and HTTP interface automation, adds a project generator, richer assertions, data driven cases and an XTestRunner report. It installs from PyPI and its CLI does most of the work, but the project is Chinese-first in its documentation and the report dependency is a separate package.

**SeldomQA/seldom** — Seldom automation testing framework based on unittest

- Repository: https://github.com/SeldomQA/seldom
- Website: https://seldomqa.github.io/
- Stars: 852 · Forks: 329
- Language: Python
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/seldomqa-seldom

## One framework over three automation surfaces

Seldom is an automation testing framework built on unittest. That foundation is the defining choice, and it explains almost everything else about the project. There is no new test case model to learn, no plugin registry, no fixture DSL. A test is a class, a method is a test, and the runner is the unittest runner with additions.

What sits on top is the breadth. The feature list calls it a full functional testing framework for web, app and API. The keyword set in the project metadata names the three underlying drivers: selenium, appium and requests. The dependency list backs that up with appium-python-client pinned to a 5.x range, and the package keywords list selenium, appium, requests and unittest together.

So the same test style can drive a browser through Selenium, a native mobile app through Appium, and an HTTP service through requests. The CLI reinforces this split with separate options, where the browser option accepts chrome, edge, firefox or chromium for the web cases, and a separate base-url option serves the HTTP cases.

The audience is a Python testing team that has outgrown a pile of scripts. The value proposition is not a new capability but a common shape: one project layout, one way to write cases, one report format, whether the target is a web page or a REST endpoint.

## The CLI is the entry point, and the scaffolded project is the contract

The command line interface is the main surface of the framework. It is built on typer, and the entry point is registered in the project metadata as a script named seldom, which maps to seldom.cli:app.

Creating a project is a single command with a type switch, and the documentation gives all three variants at once.

```shell
> seldom -api myapi  # API automation test project.
> seldom -app myapp  # or App automation test project.
> seldom -web myweb  # or Web automation test project.
```

The generated layout is identical in shape for all three, and the documentation names the role of each directory.

```shell
myweb/
├── test_dir/
│   ├── __init__.py
│   └── test_sample.py
├── test_data/
│   └── data.json
├── reports/
└── confrun.py
```

test_dir is the test case directory, test_data holds test data files, reports collects the test report output, and confrun.py is the run configuration file. Having a fixed run configuration file rather than scattered settings is what makes a Seldom project portable between a laptop, a CI runner and a colleague's machine.

One instruction in the documentation is unusual enough to repeat, because it is stated as a correction rather than a tip. The documentation marks right-clicking to run the case in PyCharm as the wrong way, and marks running it through the command line tool as the right way. The reason is implied by the project layout: the report directory and the configuration file are populated by the CLI, so a PyCharm right-click run bypasses the path that produces the report and the environment settings.

The run command is the same shape as the create command.

```shell
> seldom -p test_dir # 运行 test_dir 测试目录
```

Other options in the help output cover a lot of ground: a log level setting that accepts TRACE, DEBUG, INFO, SUCCESS, WARNING and ERROR, running a single module, class or method with the mod option, a rerun count for failed cases, a report output path, a collect option for gathering cases without running them, and a level option that parses cases at data or case granularity.

## Reruns, case collection and the har2case and swagger2case converters

Several CLI options point at features that go beyond running tests, and they are the ones that make Seldom interesting for a team that already has a lot of traffic capture and API documentation.

The rerun option takes an integer and is described as the number of times a failed use case is run again. In practice this is a flake-tolerance knob. A test that fails once because an element took an extra second to appear can be given a second attempt, and the report will show the retry.

The collect option gathers project test cases without running them, which is what you want when you want to see the inventory of a suite or feed it into another system.

Two converters are worth calling out. The har2case option turns a HAR file into a Seldom test case, and the swagger2case option does the same from a Swagger file. HAR is the recording format browsers use, so a HAR capture of a request flow can be turned into an HTTP test case without writing the request code by hand. Swagger describes an API, so the swagger2case path generates cases from the specification.

The api-excel option runs the API test cases that live in an Excel file, and openpyxl is in the dependency list to serve it. The case-json option points at test case files in JSON, and jsonschema is a dependency, which is how the framework validates those files against a schema rather than trusting their shape.

The level option controls how cases are parsed, with data and case as the two values and data as the default. That distinction is about what a data-driven case expands into: a single case with parameters, or several cases generated from the data. It is the lever that decides how much of your data table becomes a separate reported test.

## Data driven cases and a dependency list that shapes what you can do

Data driven testing is listed as a headline feature, and the framework supports it from the data files in test_data as well as from Excel.

The dependency list explains the breadth of the supporting features better than the feature bullets do. The project depends on typer for the CLI, loguru for logging, XTestRunner for the report, openpyxl for Excel, pyyaml for configuration, jsonschema for validating data files, jmespath for querying JSON responses, pymysql for database access, genson for schema generation, python-dateutil for date handling and pycryptodome for crypto operations.

Two of those deserve comment. jmespath is a query language for JSON, which is how assertions against an API response are expressed without hardcoding a chain of dictionary lookups. genson infers a JSON schema from sample data, which pairs with jsonschema: you generate the schema from the payload and then validate responses against it.

pycryptodome is the entry that surprises people, since it is not a testing dependency in the usual sense. It means the framework can sign or decrypt request payloads, which matters for an API that expects signed requests rather than a plain token.

The environment constraint is explicit in the project metadata: requires-python is >=3.9,<4.0, and the classifier list names Python 3.9 through 3.14. The build backend is poetry-core, with a configured package source pointing at the Douban mirror of PyPI, which is a hint about where the project is developed and who it serves.

## The report is a separate distribution, and the docs site is the real reference

The report integration deserves a separate look because the dependency list tells you that XTestRunner is a separate package with its own version constraint, at least 1.8.6. The project describes it as a modern, good-looking test report, and the requirement appears in both the pyproject dependency list and the requirements.txt file.

The consequence is that the report is a second project you depend on and upgrade, and it is not bundled with the framework. If you pin seldom for reproducibility, you should pin XTestRunner at the same time, and a mismatch there is the sort of thing that shows up as a broken report rather than a failing import.

The repository also carries a CHANGES.md, a docs directory, a description.rst for PyPI, an api_case directory, a demo directory and a tests directory. The demo directory mirrors the scaffolded project structure with confrun.py, run.py, test_dir and test_data, so the sample a new user reads is the same shape as the one the generator produces.

The documentation site is at seldomqa.github.io and the package metadata points its Homepage and Documentation URLs there. The README is explicitly bilingual in places but the tutorial body, the directory explanation and the sample run output are in Chinese, so a team working in English will be reading the site rather than the README for most detail.

The project is Apache-2.0 licensed with the LICENSE file referenced from the project metadata, which is a permissive grant with an explicit patent clause and no copyleft obligation.

## Where Seldom is the wrong tool

The first wrong-tool case is a team that wants pytest. Seldom is built on unittest, not pytest, and the whole project shape follows from that. If your organisation has standardised on pytest with its fixtures, markers, plugins and reporting ecosystem, adopting Seldom means working inside unittest's discovery and assertion model instead, and the reports and CI integrations you already have will not apply.

The second case is a team that wants everything in one language but a different driver. Seldom's app support goes through Appium, which means a real device or an emulator, and the mobile half of the framework inherits all of Appium's setup burden. A project whose mobile testing is a small part of the whole is paying for that complexity in the framework's centre of gravity.

The third case is anyone needing English documentation from the repository itself. The README's quick start, the directory explanations and the example output are in Chinese, and the help output shown in the documentation is likewise Chinese. The API is stable enough to read from the site, but the first-run experience is not the one an English-speaking team would design.

On maintenance, the last push was on 2026-09-01 and the project has no GitHub releases, so the version to track is the one in the project metadata, 3.14.2. The date of the last push matters for a test framework, because a framework that stops tracking a new browser version or a new Appium client eventually fails for reasons that have nothing to do with your tests. The dependency ranges are already modern, with appium-python-client on 5.x and typer at 0.24 or later, which suggests the project is being kept current, but the version number in the metadata is what your lockfile should follow.

## Conclusion

Seldom suits a Python team that already thinks in unittest and wants one framework for browser, mobile and HTTP automation rather than three separate harnesses, and the generator plus CLI keep the project structure consistent across testers. It does not suit a team that standardised on pytest, and it does not suit anyone who wants the test report included for free, since XTestRunner is a separate distribution with its own version constraint. Before adopting, run seldom --help and compare the options against your CI needs, confirm the XTestRunner version separately, and note that the last push was on 2026-09-01 with the version recorded in the project metadata at 3.14.2.

## FAQ

### How do I install Seldom?

Install the released package with pip install seldom. To follow the latest version on the master branch instead, the documentation shows pip install -U git+https://github.com/SeldomQA/seldom.git@master, with a Gitee mirror URL given as an alternative.

### How do I create a Seldom test project?

Use the CLI with a project type flag: seldom -api myapi for an API project, seldom -app myapp for an app project and seldom -web myweb for a web project. The generator creates a test_dir for cases, a test_data directory for data files, a reports directory and a confrun.py run configuration file.

### Which browsers can Seldom run web tests against?

The browser option accepts chrome, edge, firefox and chromium, and it needs the path option to be set. The base-url option separately points the HTTP automation tests at a service, and also requires the path.

### Can Seldom generate test cases from HAR or Swagger files?

Yes. The har2case option converts a HAR file into a Seldom test case, and the swagger2case option converts a Swagger file the same way. The api-excel option runs API test cases stored in an Excel file instead.

### What Python versions and licence does Seldom support?

The project metadata requires Python >=3.9,<4.0 and the classifiers cover Python 3.9 through 3.14. Seldom is licensed under Apache-2.0 with the LICENSE file referenced from the project metadata.

## Sources

- [Issues](https://github.com/SeldomQA/seldom/issues)
- [License: Apache-2.0](https://github.com/SeldomQA/seldom/blob/master/LICENSE)
- [Project website](https://seldomqa.github.io/)
- [README](https://github.com/SeldomQA/seldom/blob/master/README.md)
- [SeldomQA/seldom on GitHub](https://github.com/SeldomQA/seldom)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/seldomqa-seldom