Fix type annotations and improve code quality

.github/copilot-instructions.md

@@ -0,0 +1,57 @@
+# Tavern AI Coding Agent Instructions
+
+This guide enables AI coding agents to be productive in the Tavern codebase. It summarizes architecture, workflows, conventions, and integration points unique to Tavern.
+
+## Big Picture Architecture
+- **Tavern** is a pytest plugin, CLI tool, and Python library for automated API testing using YAML-based test files.
+- Supports both **RESTful** and **MQTT** APIs. Key logic lives in `tavern/` (core, request, response, helpers) and `_core/`, `_plugins/` for extensibility.
+- Example setups (HTTP, MQTT, cookies, gRPC, etc.) are in `example/` and `components/`—useful for integration and advanced usage patterns.
+- Tests are organized in `tests/unit/` (Pytest-based unit tests) and `tests/integration/` (integration tests, often using Dockerized servers).
+
+## Developer Workflows
+- **Run all tests:**
+  - Unit: `tox` (requires `tox` installed)
+  - Integration: `tox -c tox-integration.ini` (requires Docker)
+  - Individual YAML tests: `pytest test_*.tavern.yaml`
+- **MQTT/HTTP integration examples:**
+  - Start services: `docker compose up --build` in relevant example/component folder
+  - Run tests: `pytest` in another terminal
+- **Formatting:**
+  - Use `ruff format` for code style. Enable pre-commit hook: `pre-commit install`
+- **Dependencies:**
+  - Install with `pip install -r requirements.txt` for development
+
+## Project-Specific Conventions
+- **Test files:** Must be named `test_*.tavern.yaml` for Pytest discovery.
+- **YAML test structure:** Each file contains one or more tests, each with one or more stages (request/response pairs).
+- **Custom validation:** Utility functions and plugins live in `_core/`, `_plugins/`, and can be referenced in YAML tests.
+- **Integration tests:** Use Docker containers for realistic server setups. See `example/` and `components/` for patterns.
+- **Logging/config:** See `tests/logging.yaml` and example configs for customizing output and test environments.
+
+## Integration Points & External Dependencies
+- **Pytest**: Main test runner and plugin system.
+- **Docker**: Used for integration tests and example environments.
+- **MQTT**: Uses `paho-mqtt` for message passing; see `example/mqtt/` for setup.
+- **HTTP**: Uses `requests` for HTTP requests.
+- **YAML**: Test syntax and schema validation via `pyyaml` and `pykwalify`.
+- **Other**: JWT handling (`pyjwt`), colorized logs (`colorlog`).
+
+## Key Files & Directories
+- `tavern/`: Core implementation (entry, core, helpers, request, response)
+- `example/`, `components/`: Advanced and integration examples
+- `tests/unit/`, `tests/integration/`: Test suites
+- `requirements.txt`, `tox.ini`, `tox-integration.ini`: Dependency and test configs
+- `README.md`, `docs/`: High-level documentation and usage
+
+## Patterns & Examples
+- **Multi-stage tests:** See YAML files in `example/` for chaining requests/responses.
+- **MQTT listener/server:** See `example/mqtt/` for Docker Compose, server, and listener patterns.
+- **Custom plugins:** Extend via `_plugins/` and reference in YAML.
+
+---
+
+For more details, see [README.md](../README.md) and [docs/](../docs/).
+
+---
+
+**Feedback:** If any section is unclear or missing, please specify which workflows, conventions, or architectural details need further explanation.

.github/workflows/examples.yml

@@ -0,0 +1,124 @@
+name: Test Getting Started Examples
+
+on:
+  push:
+    paths:
+      - 'example/getting_started/**'
+      - 'docs/source/**'
+  pull_request:
+    paths:
+      - 'example/getting_started/**'
+      - 'docs/source/**'
+
+jobs:
+  test-getting-started:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r example/getting_started/requirements.txt
+
+    - name: Start test server
+      run: |
+        cd example/getting_started
+        python server.py &
+        sleep 5
+
+    - name: Run basic API tests
+      run: |
+        cd example/getting_started
+        python -m pytest test_basic_api.tavern.yaml -v
+
+    - name: Run marks and fixtures tests
+      run: |
+        cd example/getting_started
+        python -m pytest test_marks_and_fixtures.tavern.yaml -v
+
+    - name: Run external functions tests
+      run: |
+        cd example/getting_started
+        python -m pytest test_external_functions.tavern.yaml -v
+
+    - name: Run all tests with coverage
+      run: |
+        cd example/getting_started
+        python -m pytest *.tavern.yaml -v --html=report.html --self-contained-html
+
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: test-results-${{ matrix.python-version }}
+        path: example/getting_started/report.html
+
+  docker-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Build and test with Docker
+      run: |
+        cd example/getting_started
+        docker build -t tavern-getting-started .
+
+    - name: Run Docker Compose tests
+      run: |
+        cd example/getting_started
+        docker-compose up --build --abort-on-container-exit
+
+  documentation-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install documentation dependencies
+      run: |
+        pip install sphinx sphinx-rtd-theme
+
+    - name: Build documentation
+      run: |
+        cd docs
+        make html
+
+    - name: Check for broken links
+      run: |
+        cd docs
+        python -c "
+        import os
+        import re
+        broken_links = []
+        for root, dirs, files in os.walk('build/html'):
+            for file in files:
+                if file.endswith('.html'):
+                    with open(os.path.join(root, file), 'r') as f:
+                        content = f.read()
+                        # Check for common broken link patterns
+                        if 'example/getting_started/' in content:
+                            print(f'Found reference to getting_started in {file}')
+        "

.github/workflows/pylint.yml

@@ -0,0 +1,24 @@
+name: Pylint
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pylint
+        pip install -r requirements.txt
+    - name: Analysing the code with pylint
+      run: |
+        pylint $(git ls-files '*.py') --output-format=text --reports=y

.gitignore

@@ -126,3 +126,4 @@ bazel-tavern
 bazel-testlogs
 
 example/grpc/proto
+node_modules