Skip to content

Commit 4e7eb9d

Browse files
MishaKavclaude
andauthored
docs: add prerequisites section and troubleshooting for pytest-cov installation (#226)
Fixes #163 Added comprehensive documentation to help users avoid the "unrecognized arguments" error when pytest-cov is not installed: 1. Added Prerequisites section before Quick Start with: - Python version requirements (3.6+ supported, 3.9+ recommended) - Clear explanation that pytest-cov is required for --cov flags - Collapsible Python version compatibility matrix 2. Added troubleshooting entry for "Unrecognized Arguments Error" with: - Clear error message example - Root cause explanation - Multiple solution options (pip, requirements.txt, pyproject.toml) - Workflow integration example 3. Updated Table of Contents to include new sections This multi-layer approach prevents the issue proactively while helping users who already encountered it. Co-authored-by: Claude <[email protected]>
1 parent cedb856 commit 4e7eb9d

1 file changed

Lines changed: 71 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ A GitHub Action that adds pytest coverage reports as comments to your pull reque
2525
- [Pytest Coverage Comment](#pytest-coverage-comment)
2626
- [🎯 Features](#-features)
2727
- [📋 Table of Contents](#-table-of-contents)
28+
- [📦 Prerequisites](#-prerequisites)
2829
- [🚀 Quick Start](#-quick-start)
2930
- [⚙️ Configuration](#️-configuration)
3031
- [Inputs](#inputs)
@@ -44,6 +45,7 @@ A GitHub Action that adds pytest coverage reports as comments to your pull reque
4445
- [Multiple Files (Monorepo)](#multiple-files-monorepo)
4546
- [🔧 Troubleshooting](#-troubleshooting)
4647
- [Comment Not Appearing](#comment-not-appearing)
48+
- [Unrecognized Arguments Error](#unrecognized-arguments-error)
4749
- [Coverage Report Too Large](#coverage-report-too-large)
4850
- [GitHub Step Summary Too Large](#github-step-summary-too-large)
4951
- [Files Not Found](#files-not-found)
@@ -56,6 +58,32 @@ A GitHub Action that adds pytest coverage reports as comments to your pull reque
5658

5759
</details>
5860

61+
## 📦 Prerequisites
62+
63+
Before using this action, ensure you have the following installed in your Python environment:
64+
65+
- **Python** - Version 3.6+ (Python 3.9+ recommended for latest pytest/pytest-cov versions)
66+
- **pytest** - Python testing framework
67+
- **pytest-cov** - Coverage plugin for pytest (provides `--cov` and `--cov-report` flags)
68+
69+
```bash
70+
pip install pytest pytest-cov
71+
```
72+
73+
> **Note**: The `--cov` and `--cov-report` flags used in the examples below are provided by `pytest-cov`, not pytest itself. If you see an error like `pytest: error: unrecognized arguments: --cov`, you need to install `pytest-cov`.
74+
75+
<details>
76+
<summary>Python version compatibility</summary>
77+
78+
- **Python 3.9+**: Supported by latest pytest (8.4+) and pytest-cov (6.0+) versions
79+
- **Python 3.8**: Use pytest-cov < 6.0.0 (e.g., pytest-cov 5.x)
80+
- **Python 3.7**: Use pytest-cov < 5.0.0 (e.g., pytest-cov 4.x)
81+
- **Python 3.6 and older**: Use older versions of pytest and pytest-cov
82+
83+
For most users, we recommend using **Python 3.9+** with the latest versions of pytest and pytest-cov to get the latest features and security updates.
84+
85+
</details>
86+
5987
## 🚀 Quick Start
6088

6189
Add this action to your workflow:
@@ -523,6 +551,49 @@ If you want auto-update the coverage badge on your README, you can see the [work
523551
- For `workflow_dispatch`, provide the `issue-number` input
524552
- Check if `hide-comment` is set to `false`
525553

554+
### Unrecognized Arguments Error
555+
556+
**Issue**: `pytest: error: unrecognized arguments: --cov --cov-report`
557+
558+
**Root Cause**: The `pytest-cov` plugin is not installed. The `--cov` and `--cov-report` flags are provided by `pytest-cov`, not pytest itself.
559+
560+
**Solution**:
561+
562+
Install the `pytest-cov` package in your Python environment:
563+
564+
```bash
565+
pip install pytest-cov
566+
```
567+
568+
Or add it to your `requirements.txt` or `pyproject.toml`:
569+
570+
```txt
571+
# requirements.txt
572+
pytest>=8.0.0
573+
pytest-cov>=5.0.0
574+
```
575+
576+
```toml
577+
# pyproject.toml
578+
[project]
579+
dependencies = [
580+
"pytest>=8.0.0",
581+
"pytest-cov>=5.0.0",
582+
]
583+
```
584+
585+
Make sure the installation step runs before executing pytest commands in your workflow:
586+
587+
```yaml
588+
- name: Install dependencies
589+
run: |
590+
pip install pytest pytest-cov
591+
592+
- name: Run tests with coverage
593+
run: |
594+
pytest --cov=src --cov-report=term-missing tests/
595+
```
596+
526597
### Coverage Report Too Large
527598

528599
**Issue**: "Comment is too long (maximum is 65536 characters)"

0 commit comments

Comments
 (0)