diff --git a/libs/aws/CONTRIBUTING.md b/libs/aws/CONTRIBUTING.md index 75e4710e..b7de9c16 100644 --- a/libs/aws/CONTRIBUTING.md +++ b/libs/aws/CONTRIBUTING.md @@ -76,6 +76,61 @@ To run the integration tests: make integration_test ``` +### Code Coverage + +This project uses [coverage.py](https://github.com/nedbat/coveragepy) to track code coverage during testing. Coverage reports help identify untested code paths and ensure comprehensive test coverage. + +#### Running Tests with Coverage + +To run unit tests with coverage: + +```bash +make coverage_tests +``` + +To run all integration tests with coverage: + +```bash +make coverage_integration_tests +``` + +To run a specific integration test with coverage: + +```bash +make coverage_integration_test TEST_FILE=tests/integration_tests/specific_test.py +``` + +#### Viewing Coverage Reports + +After running tests with coverage, you can view the results in several ways: + +**Terminal Report:** +```bash +make coverage_report +``` + +**HTML Report:** +```bash +make coverage_html +``` + +The HTML report will be generated in the `htmlcov/` directory. Open `htmlcov/index.html` in your browser to view detailed line-by-line coverage analysis. + +#### Coverage Configuration + +Coverage settings are configured in `pyproject.toml`: +- **Source tracking**: Only code in `langchain_aws/` is measured +- **Branch coverage**: Tracks both line and branch coverage for comprehensive analysis +- **Exclusions**: Test files and common patterns (like `pragma: no cover`) are excluded +- **Reports**: Both terminal and HTML reports show missing lines and coverage percentages + +#### Coverage Best Practices + +- Aim for high coverage on new code you add +- Use coverage reports to identify untested edge cases +- Add tests for uncovered lines when practical +- Use `# pragma: no cover` sparingly for truly untestable code (like debug statements) + ### Formatting and Linting Formatting ensures that the code in this repo has consistent style so that the diff --git a/libs/aws/Makefile b/libs/aws/Makefile index aef41994..82cbc864 100644 --- a/libs/aws/Makefile +++ b/libs/aws/Makefile @@ -1,7 +1,7 @@ ###################### # NON FILE TARGETS ###################### -.PHONY: all format lint test tests integration_tests docker_tests help extended_tests +.PHONY: all format lint test tests integration_tests docker_tests help extended_tests coverage_integration_tests coverage_integration_test coverage_tests coverage_report coverage_html ###################### # ALL TARGETS @@ -35,6 +35,21 @@ integration_test: ## Run individual integration test: make integration_test TEST test_watch: ## Run and interactively watch unit tests poetry run ptw --snapshot-update --now . -- -vv $(TEST_FILE) +coverage_integration_tests: ## Run integration tests with coverage + poetry run pytest --cov=langchain_aws --cov-report=html --cov-report=term-missing --cov-branch tests/integration_tests/ + +coverage_integration_test: ## Run specific integration test with coverage: make coverage_integration_test TEST_FILE=tests/integration_tests/integ_test.py + poetry run pytest --cov=langchain_aws --cov-report=html --cov-report=term-missing --cov-branch $(TEST_FILE) + +coverage_tests: ## Run unit tests with coverage + poetry run pytest --cov=langchain_aws --cov-report=html --cov-report=term-missing --cov-branch tests/unit_tests/ + +coverage_report: ## Generate coverage report + poetry run coverage report + +coverage_html: ## Generate HTML coverage report + poetry run coverage html + ###################### # LINTING AND FORMATTING ###################### diff --git a/libs/aws/pyproject.toml b/libs/aws/pyproject.toml index 1358b46e..4e177fa3 100644 --- a/libs/aws/pyproject.toml +++ b/libs/aws/pyproject.toml @@ -89,7 +89,33 @@ disallow_untyped_defs = "True" exclude = ["notebooks", "samples"] [tool.coverage.run] -omit = ["tests/*"] +source = ["langchain_aws"] +omit = [ + "tests/*", + "*/tests/*", + "test_*", + "*_test.py" +] +branch = true + +[tool.coverage.report] +exclude_lines = [ + "pragma: no cover", + "def __repr__", + "if self.debug:", + "if settings.DEBUG", + "raise AssertionError", + "raise NotImplementedError", + "if 0:", + "if __name__ == .__main__.:", + "class .*\\bProtocol\\):", + "@(abc\\.)?abstractmethod" +] +precision = 2 +show_missing = true + +[tool.coverage.html] +directory = "htmlcov" [build-system] requires = ["poetry-core>=1.0.0"] @@ -105,7 +131,7 @@ build-backend = "poetry.core.masonry.api" # # https://github.com/tophat/syrupy # --snapshot-warn-unused Prints a warning on unused snapshots rather than fail the test suite. -addopts = "--snapshot-warn-unused --strict-markers --strict-config --durations=5 --cov=langchain_aws" +addopts = "--snapshot-warn-unused --strict-markers --strict-config --durations=5" # Registering custom markers. # https://docs.pytest.org/en/7.1.x/example/markers.html#registering-markers markers = [ diff --git a/libs/langgraph-checkpoint-aws/CONTRIBUTING.md b/libs/langgraph-checkpoint-aws/CONTRIBUTING.md index 67ccd803..ef5a6c15 100644 --- a/libs/langgraph-checkpoint-aws/CONTRIBUTING.md +++ b/libs/langgraph-checkpoint-aws/CONTRIBUTING.md @@ -28,6 +28,157 @@ Contributions via pull requests are much appreciated. Before sending us a pull r 3. You open an issue to discuss any significant work - we would hate for your time to be wasted. +## Development Setup + +This section provides detailed instructions for setting up your development environment and running tests locally. + +### Prerequisites + +This project utilizes [Poetry](https://python-poetry.org/) v1.7.1+ as a dependency manager. + +❗Note: *Before installing Poetry*, if you use `Conda`, create and activate a new Conda env (e.g. `conda create -n langgraph-checkpoint-aws python=3.9`) + +Install Poetry: **[documentation on how to install it](https://python-poetry.org/docs/#installation)**. + +❗Note: If you use `Conda` or `Pyenv` as your environment/package manager, after installing Poetry, +tell Poetry to use the virtualenv python environment (`poetry config virtualenvs.prefer-active-python true`) + +### Installation + +All commands should be run from the `libs/langgraph-checkpoint-aws` directory: + +```bash +cd libs/langgraph-checkpoint-aws +``` + +Install all development dependencies: + +```bash +poetry install --with dev,test,lint,typing,codespell,test_integration +``` + +### Testing + +#### Unit Tests + +Unit tests cover modular logic that does not require calls to outside APIs: + +```bash +make tests +``` + +To run a specific unit test: + +```bash +make test TEST_FILE=tests/unit_tests/specific_test.py +``` + +#### Integration Tests + +Integration tests cover end-to-end functionality with AWS services: + +```bash +make integration_tests +``` + +To run a specific integration test: + +```bash +make integration_test TEST_FILE=tests/integration_tests/specific_test.py +``` + +### Code Coverage + +This project uses [coverage.py](https://github.com/nedbat/coveragepy) to track code coverage during testing. + +#### Running Tests with Coverage + +To run unit tests with coverage: + +```bash +make coverage_tests +``` + +To run all integration tests with coverage: + +```bash +make coverage_integration_tests +``` + +To run a specific integration test with coverage: + +```bash +make coverage_integration_test TEST_FILE=tests/integration_tests/specific_test.py +``` + +#### Viewing Coverage Reports + +**Terminal Report:** +```bash +make coverage_report +``` + +**HTML Report:** +```bash +make coverage_html +``` + +The HTML report will be generated in the `htmlcov/` directory. Open `htmlcov/index.html` in your browser for detailed analysis. + +### Code Quality + +#### Formatting + +Code formatting is done via [ruff](https://docs.astral.sh/ruff/rules/): + +```bash +make format +``` + +#### Linting + +Linting is done via [ruff](https://docs.astral.sh/ruff/rules/): + +```bash +make lint +``` + +To automatically fix linting issues: + +```bash +make lint_fix +``` + +#### Type Checking + +Type checking is done via [mypy](http://mypy-lang.org/): + +```bash +make lint_tests +``` + +#### Spell Checking + +Spell checking is done via [codespell](https://github.com/codespell-project/codespell): + +```bash +make spell_check +``` + +To fix spelling issues: + +```bash +make spell_fix +``` + +### Clean Up + +To clean generated files and caches: + +```bash +make clean +``` + ## Finding contributions to work on Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start. diff --git a/libs/langgraph-checkpoint-aws/Makefile b/libs/langgraph-checkpoint-aws/Makefile index d7c4d835..203a5558 100644 --- a/libs/langgraph-checkpoint-aws/Makefile +++ b/libs/langgraph-checkpoint-aws/Makefile @@ -6,7 +6,7 @@ PYTHON_FILES=. MYPY_CACHE=.mypy_cache PACKAGE_NAME=langgraph_checkpoint_aws -.PHONY: help lint format install_dev install_test install_lint install_typing install_codespell check_imports spell_check spell_fix +.PHONY: help lint format install_dev install_test install_lint install_typing install_codespell check_imports spell_check spell_fix coverage_integration_tests coverage_integration_test coverage_tests coverage_report coverage_html ###################### # LINTING AND FORMATTING @@ -72,6 +72,21 @@ integration_test: ## Run individual integration test: make integration_test TEST test_watch: ## Run and interactively watch unit tests poetry run ptw --snapshot-update --now . -- -vv $(TEST_FILE) +coverage_integration_tests: ## Run integration tests with coverage + poetry run pytest --cov=langgraph_checkpoint_aws --cov-report=html --cov-report=term-missing --cov-branch tests/integration_tests/ + +coverage_integration_test: ## Run specific integration test with coverage: make coverage_integration_test TEST_FILE=tests/integration_tests/integ_test.py + poetry run pytest --cov=langgraph_checkpoint_aws --cov-report=html --cov-report=term-missing --cov-branch $(TEST_FILE) + +coverage_tests: ## Run unit tests with coverage + poetry run pytest --cov=langgraph_checkpoint_aws --cov-report=html --cov-report=term-missing --cov-branch tests/unit_tests/ + +coverage_report: ## Generate coverage report + poetry run coverage report + +coverage_html: ## Generate HTML coverage report + poetry run coverage html + ###################### # DEPENDENCIES ###################### diff --git a/libs/langgraph-checkpoint-aws/pyproject.toml b/libs/langgraph-checkpoint-aws/pyproject.toml index a9d496d8..76a6d4fa 100644 --- a/libs/langgraph-checkpoint-aws/pyproject.toml +++ b/libs/langgraph-checkpoint-aws/pyproject.toml @@ -78,4 +78,39 @@ ignore-words-list = '' ignore_missing_imports = "True" [tool.coverage.run] -omit = ["tests/*"] +source = ["langgraph_checkpoint_aws"] +omit = [ + "tests/*", + "*/tests/*", + "test_*", + "*_test.py" +] +branch = true + +[tool.coverage.report] +exclude_lines = [ + "pragma: no cover", + "def __repr__", + "if self.debug:", + "if settings.DEBUG", + "raise AssertionError", + "raise NotImplementedError", + "if 0:", + "if __name__ == .__main__.:", + "class .*\\bProtocol\\):", + "@(abc\\.)?abstractmethod" +] +precision = 2 +show_missing = true + +[tool.coverage.html] +directory = "htmlcov" + +[tool.pytest.ini_options] +addopts = "--strict-markers --strict-config --durations=5" +markers = [ + "requires: mark tests as requiring a specific library", + "asyncio: mark tests as requiring asyncio", + "compile: mark placeholder test used to compile integration tests without running them", + "scheduled: mark tests to run in scheduled testing", +]