Andrew Vaillancourt 1b9396a2c6 Enforce docstring standards and update pre-commit

- Enforce Google-style docstrings in pre-commit hooks:
  - Add pydocstyle, pydoclint, and interrogate to Pipenv and pre-commit
  - Configure pydocstyle for PEP 257 and Google-style compliance
  - Set pydoclint to enforce function signature correctness
  - Ensure 100% function and class docstring coverage with interrogate:
    - There are some exceptions, e.g. init, module-level.
    - More exceptions can be added if the tooling is found to be too
      strict.

- Refine Black hook ordering to ensure all hooks run on formatted files:
  - Fail commit if formatting is needed (--check)
  - Auto-format files in a separate step
  - Prevent bypassing docstring checks by staging unformatted files

- Ensure return type consistency (DOC203 best practices):
  - Require both return type hints (-> type) and docstring return types
  - Explain rationale for requiring both:
    - Type hints help with static analysis and runtime type checking
    - Docstring return types improve readability and documentation clarity
    - Pre-commit hooks validate consistency across both formats
  - Update pre-commit hooks to explicitly check for this requirement

- Restructure pre-commit and linting configuration:
  - Move .pydocstyle.ini, .flake8, and pyproject.toml to the root
  - Update pre-commit hooks to reference these configs in the new structure

- Modify tox.ini to prevent packaging errors and improve workflow:
  - Add `skipsdist = True` to disable setuptools packaging
  - Set `usedevelop = False` to prevent unintended package installation
  - Ensure `tox` only runs documentation and linting tasks
  - Aligns with StarlingX repository standards and prevents conflicts
  - Retain the pre-commit/ directory for potential future hooks

- Update documentation and improve contributor guidance:
  - Add CONTRIBUTING.rst with detailed contribution guidelines
  - Create contributors.rst in doc/source for Sphinx-rendered docs
  - Link contributors.rst in index.rst for visibility in generated docs
  - Ensure contributing.rst references the latest CONTRIBUTING.rst
  - Document VSCode and PyCharm auto-doc settings in CONTRIBUTING.rst

This commit ensures consistent docstring enforcement, improves
pre-commit integration, aligns with best practices, and enhances
contributor documentation.

Change-Id: Iba282c20502adb81a7739ec6c3ed8b6f3bc45077
Signed-off-by: Andrew Vaillancourt <andrew.vaillancourt@windriver.com>

2025-02-18 14:35:58 -05:00

8.5 KiB

Raw Blame History

stx-test

StarlingX Test repository for automated test cases.

This repository contains the test framework and test cases for verifying StarlingX. The test framework provides tools for configuration, automation, and execution of tests, with the ability to run against diverse StarlingX lab environments.

Pre-Requisites

To use this repository, ensure the following requirements are met:

Operating System:
- Ubuntu 22.04 or later.
Network Requirements:
- The RunAgent (test execution machine) must:
  - Have internet access for pulling images and dependencies.
  - Be able to connect to your StarlingX system(s) via SSH.

Required Tools: Install the following tools:

# Python 3.11
sudo apt update
sudo apt install -y python3.11 python3-pip

# pipenv
pip install --user pipenv

Setup and Installation

Clone the Repository:

git clone https://opendev.org/starlingx/test.git
cd test

Setup Gerrit for Code Review: The procedure to set up Gerrit for StarlingX is the same as for other projects hosted on OpenDev, such as OpenStack. Refer to the OpenStack Contributor Guide for detailed instructions.
- Key Setup and Repository Configuration:
```
# Generate an SSH key (recommended: ED25519; RSA is also supported)
ssh-keygen -t ed25519 -C "<your email address>"
ssh-add ~/.ssh/id_ed25519

# Alternatively, generate an RSA key for compatibility with older systems:
ssh-keygen -t rsa -b 4096 -C "<your email address>"
ssh-add ~/.ssh/id_rsa
```
  - Add your SSH key to Gerrit:
    - Navigate to https://review.opendev.org/settings/#SSHKeys.
    - Copy the contents of your public key file (~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub).
    - Paste the key into the SSH key field on the Gerrit settings page.
- Sign the Individual Contributor License Agreement (ICLA): Projects hosted on OpenDev, including StarlingX, require signing the OpenStack Individual Contributor License Agreement (ICLA). This step is outlined in the OpenStack Contributor Guide and the OpenDev Developer Documentation. Follow these instructions to complete the process before submitting changes.
- Fetch Gerrit Hooks: Fetch Gerrit hooks immediately after cloning to enable automatic Change-Id generation during commits and verify your SSH key setup:
```
git review -s
```
  Example output:
```
Creating a git remote called 'gerrit' that maps to:
        ssh://<open-review-email-or-username>@review.opendev.org:29418/starlingx/test.git
```
  If there is an issue with your SSH configuration (e.g., missing or incorrect SSH key), you will see an error message indicating the problem, such as "Permission denied (publickey)".
  - (Optional) If you cloned the repository using HTTPS or need Gerrit hooks:
    - Add a Gerrit remote (only needed if the default remote does not point to Gerrit).
      git remote add gerrit ssh://<your-gerrit-username>@review.opendev.org/starlingx/test.git

Install Python Dependencies:

# Create and activate a virtual environment
pipenv shell

# Sync project dependencies
pipenv sync

Install Pre-Commit Hooks:

# Install pre-commit hooks for linting and formatting (run in the repository's root directory)
pre-commit install

Configuration

The framework relies on configuration files found under the config directory. These include settings for labs, Docker, Kubernetes, and logging. Default files are provided, but you can customize configurations using CLI options.

Steps to Configure

Lab Configuration (`config/lab/files/default.json5`):
- Holds lab details such as floating IPs, type, and capabilities.
- For custom setups:
  - Use a template file (e.g., template_simplex.json5) as a base.
  - Update use_jump_host and jump_server_config if a jump server is used.
Docker Configuration (`config/docker/files/default.json5`):
- Specify credentials for Docker registries used during testing.

Lab Capability Scanner:

Automatically detect and update lab capabilities:

python scripts/lab_capability_scanner.py --lab_config_file=<lab_config_file>

You are now ready to execute tests!

Running Tests

Basic Example: Run a specific test case:

python framework/runner/scripts/test_executor.py --tests_location=<testcase_location>

Custom Configurations: Use non-default configurations:

python framework/runner/scripts/test_executor.py \
  --tests_location=<testcase_location> \
  --lab_config_file=<config_location>

Example:

python framework/runner/scripts/test_executor.py \
  --tests_location=testcases/cloud_platform/sanity \
  --lab_config_file=config/lab/files/custom_config.json5

UI Testing (Optional): Install Chrome for running WebDriver-based UI tests:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt -f install
google-chrome --version

Contribution

Coding Standards:
- Ensure your code adheres to project conventions. For detailed guidelines, see CONTRIBUTING.rst.
- Pre-commit hooks will run automatically on every commit once installed to ensure formatting and linting.
- Tools Enforced by Pre-Commit Hooks:
  - pre-commit
  - black
  - isort
  - flake8
  - pydocstyle
  - pydoclint
  - interrogate
Submitting Changes:
- Ensure your commit messages adhere to the guidelines in the OpenStack Git Commit Message Guidelines.
- Submit changes for Gerrit review using the following example:
```
git commit -s # include sign-off
git review
```

8.5 KiB Raw Blame History