Metadata-Version: 2.1
Name: pytest-f3ts
Version: 1.0.7
Summary: Pytest Plugin for communicating test results and information to a FixturFab Test Runner GUI
Author: Duncan Lowder
Author-email: duncan@fixturfab.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: fastapi (>=0.101.0,<0.102.0)
Requires-Dist: pydantic[email] (>=1.10.10,<2.0.0)
Requires-Dist: pytest (>=7.2.1,<8.0.0)
Requires-Dist: pytest-html (>=4.1.1,<5.0.0)
Requires-Dist: pytest-reportlog (>=0.4.0,<0.5.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: sqlalchemy-file (>=0.5.0,<0.6.0)
Requires-Dist: tenacity (>=8.2.3,<9.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Requires-Dist: websocket-client (>=1.6.2,<2.0.0)
Requires-Dist: websockets (>=11.0.3,<12.0.0)
Description-Content-Type: text/markdown

# pytest-f3ts

Use your `pytest` test plans with the FixturFab Test Executor!

## Manage, Execute, and Support your Hardware Test Plan Deployments

Leverage the amazingness that is `pytest` and all of the community support to
implement hardware tests for circuit boards, sub-assemblies and more!

Simply add the `pytest-f3ts` plugin and a f3ts.toml file to your test plan and
start executing your tests using the FixturFab Test Executor.

## Installation into a Project using `poetry`

The built wheels are stored within a Google Cloud Artifact Registry. To access
this registry and install the package, you will need to install the
[`gcloud`](https://cloud.google.com/sdk/docs/install) command line tool and
authenticate with the registry.

1. Install [`gcloud` CLI Application](https://cloud.google.com/sdk/docs/install)
2. Add the Google Artifact Registry as a `poetry` plugin
    ```bash
    poetry self add keyrings.google-artifactregistry-auth
    ```
3. Authenticate with the Google Artifact Registry. Copy and paste the following into your `pyproject.toml` file:
    ```bash
    gcloud auth login
    ```
   1. Verify that you are connected to the `[test-runner-404519]` project.
4. Add the Google Artifact Registry as a `poetry` repository
    ```toml
    [[tool.poetry.source]]
    name = "pytest-f3ts"
    url = "https://us-west1-python.pkg.dev/test-runner-404519/pytest-f3ts/simple/"
    secondary = true
    ```
5. Install the package
    ```bash
    poetry add pytest-f3ts
    ```

Note: If you're having issues installing the package, you can double check
the URL by running the following command:

```bash
gcloud artifacts print-settings python \
    --project=test-runner-404519 \
    --repository=pytest-f3ts \
    --location=us-west1
```

Resources:

- [Google Artifact Registry Authentication Setup](https://cloud.google.com/artifact-registry/docs/python/authentication?hl=en)
- [Poetry and GAR Stackoverflow Post](https://stackoverflow.com/questions/74106823/working-poetry-project-with-private-dependencies-inside-docker/75218763#75218763)

## Development

### Environment Setup

[`poetry`](https://python-poetry.org/) is used for dependency management and
[`pre-commit`](https://pre-commit.com/) is used to identify simple issues
before submission for code review. Once installed, run the following commands
to setup your development environment:

```bash
poetry install
pre-commit install
```

### Making changes

Use the following process when making changes to the module:

1. Create new test cases
2. Write new feature code and/or bugfixes
3. Write documentation for new features
4. Run pre-commit checks and tests prior to committing

To run the pre-commit checks, simply run the following:

```bash
poetry run pre-commit run --all-files
```

### Git Commit Message Format

We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for our commit messages.
This allows us to automatically generate changelogs and version numbers.

Brief Overview:

* `fix:` - Fixes a bug
* `feat:` - Adds a new feature
* `docs:` - Updates documentation
* `style:` - Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* `refactor:` - A code change that neither fixes a bug nor adds a feature
* `perf:` - A code change that improves performance
* `test:` - Adding missing tests or correcting existing tests
* `chore:` - Changes to the build process or auxiliary tools and libraries such as documentation generation
* `ci:` - Changes to our CI configuration files and scripts
* `BREAKING CHANGE:` - A commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope,
introduces a breaking API change (correlating with MAJOR in semantic versioning).

### Code Quality Tools

#### `black`

[`black`]() is used for code formatting, this is configured within `pyproject.toml`

To run `black` manually, run:

```bash
poetry run black .
```

#### `flake8`

[`flake8`](https://flake8.pycqa.org/en/latest/) is used to enforce additional
style guidelines.

To run `flake8` manually, run:

```bash
poetry run flake8 ./pytest_f3ts
```

#### `isort`

[`isort`](https://pycqa.github.io/isort/) is used to automatically reformat
python module import statements.

To run `isort` manually, run:

```bash
poetry run isort .
```


#### `pre-commit`

To automatically check if code is ready to be committed and pushed to Gitlab
[`pre-commit`](https://pre-commit.com/) is used. This is configured via the
`.pre-commit-config.yml` file.

To run `pre-commit` manually, run:

```bash
poetry run pre-commit run --all-files
```

### Documentation Generation

[`mkdocs`](https://www.mkdocs.org/) is utilized along with [`mkdocs-material`](https://github.com/squidfunk/mkdocs-material) to generate documentation for
this project.

The `docs` directory contains the general structure for the documentation in
the form of markdown files. To autogenerate additional documentation from
docstrings, the [`mkdocstrings`](https://mkdocstrings.github.io/) module is
used.

#### Developing documentation with the live server

When creating additional documentation it's useful to run the `mkdocs` server
which will live-reload the webpages as you make changes. To start this server,
run the following in a terminal: ### `pre-commit`



```bash
poetry run mkdocs serve
```

#### Adding a new file for autodocumentation

To add a new python file to the autodocumentation, open the `docs/reference.md`
file. Add a new header to the file, and then add the line
`::: pytest_f3ts.{new_file_name}`, this will signal to `mkdocstrings` to
process the new file when building the documentation


### Manually building and uploading a wheel

```bash
poetry config repositories.pytest-f3ts https://us-west1-python.pkg.dev/test-runner-404519/pytest-f3ts/

# On windows you will need to run the following command as two separate commands
# and paste the token into the password prompt for the second command.
gcloud auth print-access-token | poetry config http-basic.pytest-f3ts oauth2accesstoken

poetry publish --repository pytest-f3ts --build
```

## Pipeline Setup

The pipeline is configured via the `.gitlab-ci.yml` file. The pipeline is
configured to run the following stages:

- `linting`: Runs the `black`, `flake8`, and `isort` checks
    - Occurs on all merge requests and is required to pass before a merge
      request can be merged
- `version`: Runs the `gen-semver.py` command to update the version number
    - Occurs after a merge request is accepted.
    - `[skip ci]` is added to a new Git Commit to prevent the pipeline from
      running again
- `build`: Builds the package and uploads it to the Gitlab package registry
    - Triggered by new tags, which are created by the `version` stage

