Metadata-Version: 2.4
Name: behave-zap
Version: 0.1.0
Summary: Reusable Behave hooks for Selenium + OWASP ZAP integration.
Author: testingsoul
License-Expression: MIT
Project-URL: Homepage, https://github.com/testingsoul/behave-zap
Project-URL: Repository, https://github.com/testingsoul/behave-zap
Project-URL: Issues, https://github.com/testingsoul/behave-zap/issues
Keywords: behave,zaproxy,owasp-zap,dast,selenium,security-testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: behave==1.2.6
Requires-Dist: selenium>=4.34.0
Requires-Dist: zaproxy>=0.3.2
Dynamic: license-file

# behave-zap

`behave-zap` is a working Python library that integrates **Behave** and **OWASP ZAP** into a single, reusable web testing + DAST execution model.

It is designed for teams that want:
- Functional browser automation and security scanning in the same run
- Per-feature control of active scan targets
- A final consolidated ZAP report with all discovered alerts
- A CI-friendly flow with reference pipeline examples

![integration](docs/DAST_flow.png)

## Why this library

Security scanning is often bolted on after functional testing. `behave-zap` makes DAST a first-class part of your Behave lifecycle:
- Hook-based orchestration for `before_all`, `after_feature`, and `after_all`
- Chrome-focused web automation primitives for page objects and driver setup
- Feature-level attack-surface segmentation through target mapping
- Final report generation after full test execution

## Core architecture

- `behave_zap/hooks.py`
  - Behave lifecycle integration
  - ZAP initialization, passive/active scan orchestration, final reports
- `behave_zap/web.py`
  - Chrome WebDriver creation
  - Context + page-object base classes (`PageObject`, `Button`, `InputText`, etc.)
- `test/environment.py`
  - Thin project adapter that delegates to the library runner

## Installation

Install as editable package in this repository:

```bash
pip install -e .
```

Install from a consumer project:

```bash
pip install behave-zap
```

## Quick start

1. Configure DAST in `test/conf/properties.cfg`.
2. Define feature-specific active scan targets using `targets_<feature_file_name>`.
3. Run ZAP in daemon mode.
4. Execute Behave scenarios (optionally with `@dast` tag).
5. Collect final reports from `test/output/zapreport-final.html` and `test/output/zapreport-final.xml`.

## Feature-level target strategy

Active scan targets are configured per feature file:
- `targets_login=...`
- `targets_product=...`
- `targets_customer_feedback=...`

If a feature has no `targets_<feature_name>` entry, active scan is skipped for that feature. This improves control of attack surface and reduces noisy scans.

## CI and pipeline example

Reference workflow examples are provided as documentation (not active GitHub Actions):
- `docs/examples/github-workflows/ci_dast.yml`

The pipeline example uses the `testingsoul` action created for this project to annotate PRs from ZAP results:
- https://github.com/testingsoul/zap-annotations
- https://github.com/marketplace/actions/zap-annotations

## Documentation

- Test execution guide: [docs/test.md](docs/test.md)
- Full library experience: [docs/library-experience.md](docs/library-experience.md)

## Release and Publish

Best practice for public libraries is:
1. Validate locally (`build` + `twine check`).
2. Publish to TestPyPI.
3. Create a GitHub Release tag.
4. Publish to PyPI automatically from GitHub Actions (Trusted Publisher/OIDC recommended).

### Release checklist

1. Update version in `behave_zap/version.py`.
2. Add release notes in `CHANGELOG.md`.
3. Build and validate package:
   ```bash
   python -m build
   python -m twine check dist/*
   ```
4. Publish to TestPyPI and test install.
5. Create git tag and GitHub Release (for example `v0.1.1`).
6. Publish to PyPI.

### Manual deploy script

Use:

```bash
./scripts/deploy.sh --testpypi
./scripts/deploy.sh --pypi
```

Script path:
- `scripts/deploy.sh`

### Automatic publish workflow (recommended)

Reference-only workflow example:
- `docs/examples/github-workflows/publish-pypi-release.yml`

This workflow publishes when a GitHub Release is created.
