py-teststand 0.2.3

Community object-oriented Python 3 bindings for the National Instruments TestStand™ COM API

py-teststand

Community object-oriented Python 3 bindings (twin API) for the National Instruments TestStand™ COM API.

Table of Contents

• py-teststand
  • Table of Contents
  • 📖 Overview
    • 📛 Name
  • ⚠️Transparency
  • 🚧 Project Status
    • 🤖 AI-Assisted Development
  • ⚡ Quick Start
  • ✨ Features
  • 🚀 Installation
    • ⚡ uv
    • 📦 pip
  • 🔗 Compatibility
  • 🎯 Design Goals
  • 🛠️ Implementation Notes
    • ⚙️ Type Library Generation
  • 🧰 Technical Stack
  • 🤝 Contributing
  • 📈 Popularity Over Time
  • ⚖️ Legal

---

📖 Overview

py-teststand exposes the TestStand™ COM API as an object-oriented Python interface via pywin32.

📛 Name

The package is named py-teststand (with a dash) to avoid naming collision with the pytest testing framework and for easier relation to the TestStand™ test executive. The import name uses an underscore: py_teststand.

---

⚠️Transparency

🚧 Project Status

This is a hobby project, maintained on a best-effort basis and not yet under active full-time development ahead of the first release. There is no fixed release schedule or formal support, but feel free to get in touch.

Treat it as experimental: wrapper behaviour may change between releases without notice (like error catching or high level imports).

If you hit a missing TestStand™ binding, a wrong type annotation, or unexpected TestStand™ COM dispatch behavior, open an issue with a reproducible case. That is the best way to get it fixed.

For now i prefer lightweight tags based releases (i protected them in repository settings) instead of fully described ones until reach 1.0.0 release.

🤖 AI-Assisted Development

This project leverages Large Language Models (LLMs) to assist with:

• Codebase audits and refactoring.
• Test coverage analysis and generation.
• Documentation drafting.

This is an independent community project. These AI tools are used to optimize productivity and are not an official component of the project, nor do they integrate with or replace the official NIGEL™ AI Advisor provided by National Instruments. All generated code is manually reviewed by the maintainer to ensure it meets the project's quality standards.

---

⚡ Quick Start

from py_teststand import Engine

with Engine() as engine:
    with engine.get_sequence_file("my_test.seq") as sequence_file:
        with engine.new_execution(sequence_file, "MainSequence") as execution:
            execution.wait_for_end_ex(-1)
            print(f"Result: {execution.result_status}")

To see the full capabilities, run the examples suite:

uv run .\examples\launch_all_examples.py

EXAMPLES: list[tuple[str, str]] = [
    ("station_options_update", "Set station and debug options. Start here."),
    ("search_directory_manage", "Manage TestStand search directories."),
    ("variables_manage", "Create variables across scopes, then retype and remove one."),
    ("data_type_manage", "Create and evolve custom data types (container + strict enum)."),
    ("property_object_serialize", "Dump variables and typedefs to JSON and back."),
    ("sequence_build", "Build a sequence file with steps and save it."),
    ("step_insert", "Insert a step into the sequence sequence_build made."),
    ("step_insert_from_template", "Add a step from a step-type template."),
    ("analyzer_step_name_length", "Walk a sequence and report on its step names."),
    ("workspace_create", "Create a workspace and project file."),
    ("users_manage", "Create users and set their privileges."),
    ("execution_run_test_headless", "Run real pass/fail tests and read their numeric results."),
    ("ui_messages_handle", "Receive UI messages from a running sequence without a GUI."),
    (
        "execution_run_subsequence",
        "Run a sequence and read its results. Last; it shuts the engine down.",
    ),
]

ℹ️ A live TestStand™ installation is only required at runtime when COM objects are actually instantiated — not at import time.

---

✨ Features

• 🐍 Pythonic attribute access: TestStand™ COM properties are accessible via standard Python attribute notation instead of raw Dispatch calls.
• 🏷️ Type annotations: All public members carry type hints compatible with ty.
• ⚙️ TestStand™ station options provisioning: Read and write TestStand™ station-level configuration suitable for use in automated deployment pipelines (like test-station install scripts).
• 🪶 Minimal binding surface: No behavior is added beyond what the TestStand™ COM layer provides. Error conditions follow the TestStand™ COM API contract.
• 🗂️ Domain-grouped modules: Classes are organized by TestStand™ domain area for easier navigation without adding abstraction or reinterpreting behavior.
• ⚡ No live TestStand™ installation required at import time: The committed pywin32 dispatch cache allows the library to be imported and partially used (type checking, configuration building) without a TestStand™ installation present.

---

🚀 Installation

⚡ uv

uv add py-teststand

📦 pip

pip install py-teststand

---

🔗 Compatibility

Component	Versions
Windows	7 to 11
Python	3.8 to 3.14
TestStand™	2016 to 2026

ℹ️ Older TestStand™ engine versions may also work if the underlying COM interfaces have not changed, but they were not explicitly tested.

---

🎯 Design Goals

• 🐍 Python 3.8 minimum: Python 3.8 is the last CPython release with official Windows 7 support, making it suitable for long-lifecycle, air-gapped manufacturing environments where OS upgrades are not feasible. This lets you adopt Python-based automation incrementally on existing TestStand™ station hardware.
• ⚙️ TestStand™ station options as code: The TestStand™ Station Options object model is fully exposed, so search directories, model paths, station globals, and result processing configuration can be read and written programmatically. This makes station configuration reproducible and suitable for provisioners such as:
  • Terraform - via custom provider / local module (like wrapped PowerShell ones).
  • Ansible
  • Custom deployment scripts.
• 📄 No TestStand™ documentation mirroring: The library does not duplicate or paraphrase the official TestStand™ API reference in its docstrings. Reproducing NI's documentation risks creating a secondary source that drifts from the official spec over time. For authoritative descriptions of COM objects, properties, and method semantics, refer directly to the TestStand™ API Reference.

---

🛠️ Implementation Notes

⚙️ Type Library Generation

Python class stubs and interface definitions are generated from the TestStand™ COM Type Library (.tlb) using pywin32's makepy utility. The generated output is cached as a pywin32 dispatch cache module and checked into the repository, meaning a live TestStand™ installation is not required at import time — only at runtime when TestStand™ COM objects are actually instantiated.

The generation process follows this pipeline:

1. 🔍 TLB introspection: makepy reads the registered TestStand™ COM type library via the Windows registry and reflects all exposed interfaces, CoClass definitions, enumerations, and dispatch IDs.
2. 💾 Cache dump: The reflected metadata is serialized into a Python module stored under win32com/gen_py/, keyed by the TestStand™ type library GUID and version. This cache is committed to the repository so users do not need to run makepy themselves.
3. 🧩 Wrapper generation: py-teststand classes are authored on top of the cached dispatch definitions, adding Python type annotations and translating raw COM VARIANT and IDispatch returns into typed Python objects where applicable.

The bindings stay compatible across TestStand™ engine versions by tracking the stable, long-lived COM interfaces that exist across the supported range.

---

🧰 Technical Stack

Tool	Purpose
uv	Python package and project manager
ty	Static type checker for interface validation
ruff	Linter and code formatter (with strict rules)
pytest	Unit and integration test runner
pywin32	Windows COM dispatch layer and TestStand™ TLB introspection

---

🤝 Contributing

Bug reports, feature requests, and pull requests are welcome via GitHub Issues.

If you are working with the TestStand™ COM API and have improvements, fixes, or additional bindings, contributions are encouraged and will be reviewed. See CONTRIBUTING.md for development setup and guidelines.

---

📈 Popularity Over Time

---

⚖️ Legal

TestStand™ is a registered trademark of National Instruments Corporation. Refer to NI's TestStand™ licensing options for information on required licenses to operate the TestStand™ engine.

py-teststand is an independent community project and is not affiliated with, endorsed by, or maintained by National Instruments or its parent company Emerson. References to the TestStand™ API are made solely for interoperability purposes.