lib-shopware6-api-base 3.1.0__tar.gz → 3.1.2__tar.gz

{lib_shopware6_api_base-3.1.0 → lib_shopware6_api_base-3.1.2}/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.2] - 2026-06-08
+
+### Changed
+
+- **Tooling**: project automation converted to the standard BMK `Makefile`; `make test`, `make testintegration`, `make push`, `make release`, and `make bump-*` now run via the `bmk` uv-tool. The vendored `scripts/` package (plus `mk` / `mk.py`) and the dead `tests/local_testscripts/` helpers were removed.
+- **Docs**: README gained a "Development" section documenting how to run the unit suite (`make test`) and the dockware-backed integration suite (`make testintegration`), including prerequisites.
+- Refreshed dependency minimums to current releases (`pydantic`, `pydantic-settings`, `httpx2`, `lib_cli_exit_tools`, and dev/build tooling) via the bmk dependency update.
+
+### Fixed
+
+- pip-audit: ignore shared dev-venv audit noise (`aiohttp`, `paramiko`, `pyjwt`) — not dependencies of this project and absent from CI's clean env; present only because sibling editable projects share the local venv.
+
+## [3.1.1] - 2026-06-08
+
+### Fixed
+
+- pip-audit: ignore `PYSEC-2026-196` (pip 26.1.1, env-only GHA runner image, fix in pip 26.1.2, awaiting runner bump) — unblocks the scheduled CI vulnerability scan.
+
 ## [3.1.0] - 2026-06-01
 
 ### Changed

lib_shopware6_api_base-3.1.2/Makefile

@@ -0,0 +1,260 @@
+# BMK MAKEFILE 2.9.4
+# do not alter this file - it might be overwritten on new versions of BMK
+# if You want to alter it, remove the first line # BMK MAKEFILE 1.0 - then it is a custom makefile and will not be overwritten
+# bmk Makefile — thin wrapper using `uv tool install` for persistent bmk
+#
+# Usage:
+#   make test                        # run test suite
+#   make test --verbose              # forward extra flags
+#   make bump-patch                  # bump patch version
+#   make push fix login bug          # push with commit message
+#   make custom deploy                # run custom command
+#   make custom deploy --dry-run
+#
+# On every invocation, bmk is (re-)installed as a persistent uv tool
+# together with the current project's dependencies (read from ./pyproject.toml).
+# This ensures pyright, pytest, pip-audit etc. can resolve the full
+# dependency tree without PYTHONPATH hacks or a local .venv.
+#
+# Arguments after the target name are forwarded automatically.
+# You can also use ARGS="..." explicitly if preferred.
+
+SHELL := /bin/bash
+.DEFAULT_GOAL := help
+
+# Use absolute path to the uv tool binary so active virtualenvs cannot shadow it.
+BMK := $(HOME)/.local/bin/bmk
+ARGS ?=
+
+# ──────────────────────────────────────────────────────────────
+# Ensure bmk + project deps are installed as a persistent uv tool
+# ──────────────────────────────────────────────────────────────
+# --reinstall re-resolves deps on every call (fast when cached).
+# Fallback handles first-time install where --reinstall would fail.
+.PHONY: _ensure_bmk
+_ensure_bmk:
+	@uv tool install --reinstall bmk --with . 2>/dev/null || uv tool install bmk --with .
+
+# ──────────────────────────────────────────────────────────────
+# Argument forwarding via MAKECMDGOALS
+# ──────────────────────────────────────────────────────────────
+# Allows natural argument passing: make push fix login bug
+# instead of: make push ARGS="fix login bug"
+
+# All targets that accept trailing arguments
+_BMK_TARGETS := test t test-human th testintegration testi ti testintegration-human tih \
+	codecov coverage cov \
+	build bld clean cln cl run \
+	bump-major bump-minor bump-patch bump \
+	commit c push psh p release rel r \
+	dependencies deps d dependencies-update \
+	config config-deploy config-generate-examples \
+	send-email send-notification custom \
+	info logdemo
+
+ifneq (,$(filter $(_BMK_TARGETS),$(firstword $(MAKECMDGOALS))))
+  # Capture everything after the first word as extra arguments
+  _EXTRA := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
+  # Append to ARGS (so explicit ARGS="..." still works alongside)
+  override ARGS += $(_EXTRA)
+endif
+
+# ──────────────────────────────────────────────────────────────
+# Test & Quality
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: test t
+test: _ensure_bmk  ## Run test suite [alias: t]
+	$(BMK) test $(ARGS)
+t: _ensure_bmk
+	$(BMK) test $(ARGS)
+
+.PHONY: test-human th
+test-human: _ensure_bmk  ## Run test suite with human-readable output [alias: th]
+	$(BMK) test --human $(ARGS)
+th: _ensure_bmk
+	$(BMK) test --human $(ARGS)
+
+.PHONY: testintegration testi ti
+testintegration: _ensure_bmk  ## Run integration tests only [aliases: testi, ti]
+	$(BMK) testintegration $(ARGS)
+testi ti: _ensure_bmk
+	$(BMK) testintegration $(ARGS)
+
+.PHONY: testintegration-human tih
+testintegration-human: _ensure_bmk  ## Run integration tests with human-readable output [alias: tih]
+	$(BMK) testintegration --human $(ARGS)
+tih: _ensure_bmk
+	$(BMK) testintegration --human $(ARGS)
+
+.PHONY: codecov coverage cov
+codecov: _ensure_bmk  ## Upload coverage report to Codecov [aliases: coverage, cov]
+	$(BMK) codecov $(ARGS)
+coverage cov: _ensure_bmk
+	$(BMK) codecov $(ARGS)
+
+# ──────────────────────────────────────────────────────────────
+# Build & Clean
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: build bld
+build: _ensure_bmk  ## Build wheel and sdist artifacts [alias: bld]
+	$(BMK) build $(ARGS)
+bld: _ensure_bmk
+	$(BMK) build $(ARGS)
+
+.PHONY: clean cln cl
+clean: _ensure_bmk  ## Remove build artifacts and caches [aliases: cln, cl]
+	$(BMK) clean $(ARGS)
+cln cl: _ensure_bmk
+	$(BMK) clean $(ARGS)
+
+# ──────────────────────────────────────────────────────────────
+# Run
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: run
+run: _ensure_bmk  ## Run the project CLI
+	$(BMK) run $(ARGS)
+
+# ──────────────────────────────────────────────────────────────
+# Version Bumping
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: bump-major
+bump-major: _ensure_bmk  ## Bump major version (X+1).0.0
+	$(BMK) bump major $(ARGS)
+
+.PHONY: bump-minor
+bump-minor: _ensure_bmk  ## Bump minor version X.(Y+1).0
+	$(BMK) bump minor $(ARGS)
+
+.PHONY: bump-patch
+bump-patch: _ensure_bmk  ## Bump patch version X.Y.(Z+1)
+	$(BMK) bump patch $(ARGS)
+
+.PHONY: bump
+bump: bump-patch  ## Bump patch version (default for bump)
+
+# ──────────────────────────────────────────────────────────────
+# Git Operations
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: commit c
+commit: _ensure_bmk  ## Create a git commit with timestamped message [alias: c]
+	$(BMK) commit $(ARGS)
+c: _ensure_bmk
+	$(BMK) commit $(ARGS)
+
+.PHONY: push psh p
+push: _ensure_bmk  ## Run tests, commit, and push to remote [aliases: psh, p]
+	$(BMK) push $(ARGS)
+psh p: _ensure_bmk
+	$(BMK) push $(ARGS)
+
+.PHONY: release rel r
+release: _ensure_bmk  ## Create a versioned release (tag + GitHub release) [aliases: rel, r]
+	$(BMK) release $(ARGS)
+rel r: _ensure_bmk
+	$(BMK) release $(ARGS)
+
+# ──────────────────────────────────────────────────────────────
+# Dependencies
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: dependencies deps d
+dependencies: _ensure_bmk  ## Check and list project dependencies [aliases: deps, d]
+	$(BMK) dependencies $(ARGS)
+deps d: _ensure_bmk
+	$(BMK) dependencies $(ARGS)
+
+.PHONY: dependencies-update
+dependencies-update: _ensure_bmk  ## Update dependencies to latest versions
+	$(BMK) dependencies update $(ARGS)
+
+# ──────────────────────────────────────────────────────────────
+# Configuration
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: config
+config: _ensure_bmk  ## Show current merged configuration
+	$(BMK) config $(ARGS)
+
+.PHONY: config-deploy
+config-deploy: _ensure_bmk  ## Deploy configuration to system/user directories
+	$(BMK) config-deploy $(ARGS)
+
+.PHONY: config-generate-examples
+config-generate-examples: _ensure_bmk  ## Generate example configuration files
+	$(BMK) config-generate-examples $(ARGS)
+
+# ──────────────────────────────────────────────────────────────
+# Email
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: send-email
+send-email: _ensure_bmk  ## Send an email via configured SMTP
+	$(BMK) send-email $(ARGS)
+
+.PHONY: send-notification
+send-notification: _ensure_bmk  ## Send a plain-text notification email
+	$(BMK) send-notification $(ARGS)
+
+# ──────────────────────────────────────────────────────────────
+# Custom Commands
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: custom
+custom: _ensure_bmk  ## Run a custom command (make custom <name> [args...])
+	$(BMK) custom $(ARGS)
+
+# ──────────────────────────────────────────────────────────────
+# Info & Demos
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: info
+info: _ensure_bmk  ## Print resolved package metadata
+	$(BMK) info $(ARGS)
+
+.PHONY: logdemo
+logdemo: _ensure_bmk  ## Run logging demonstration
+	$(BMK) logdemo $(ARGS)
+
+.PHONY: version-current
+version-current: _ensure_bmk  ## Print current version
+	$(BMK) --version
+
+# ──────────────────────────────────────────────────────────────
+# Development
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: dev
+dev:  ## Install package with dev extras (editable)
+	uv pip install -e ".[dev]"
+
+
+.PHONY: install
+install:  ## Editable install (no dev extras)
+	uv pip install -e .
+
+# ──────────────────────────────────────────────────────────────
+# Help
+# ──────────────────────────────────────────────────────────────
+
+.PHONY: help
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-26s\033[0m %s\n", $$1, $$2}' | \
+		sort
+
+# ──────────────────────────────────────────────────────────────
+# No-op overrides for trailing argument words (MUST be last)
+# ──────────────────────────────────────────────────────────────
+# Placed after all real target definitions so the no-op recipes
+# override them.  This prevents "make push codecov fix" from
+# executing the real codecov target — "codecov" is an argument
+# to push, not a separate command.
+ifneq (,$(_EXTRA))
+$(_EXTRA):
+	@:
+endif

lib_shopware6_api_base-3.1.0/README.md → lib_shopware6_api_base-3.1.2/PKG-INFO

@@ -1,3 +1,56 @@
+Metadata-Version: 2.4
+Name: lib_shopware6_api_base
+Version: 3.1.2
+Summary: python3 base API client for shopware6
+Project-URL: Homepage, https://github.com/bitranox/lib_shopware6_api_base
+Project-URL: Documentation, https://github.com/bitranox/lib_shopware6_api_base/blob/master/README.md
+Project-URL: Repository, https://github.com/bitranox/lib_shopware6_api_base.git
+Project-URL: Changelog, https://github.com/bitranox/lib_shopware6_api_base/blob/master/CHANGELOG.md
+Author-email: bitranox <bitranox@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,shopware
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx2>=2.3.0
+Requires-Dist: lib-cli-exit-tools>=2.3.1
+Requires-Dist: orjson
+Requires-Dist: pydantic-settings>=2.14.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: rich-click
+Provides-Extra: dev
+Requires-Dist: bandit>=1.9.4; extra == 'dev'
+Requires-Dist: build>=1.5.0; extra == 'dev'
+Requires-Dist: codecov-cli>=11.2.8; extra == 'dev'
+Requires-Dist: httpx2>=2.3.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.155.2; extra == 'dev'
+Requires-Dist: import-linter>=2.11; extra == 'dev'
+Requires-Dist: jaraco-context>=6.1.2; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pynacl>=1.6.2; extra == 'dev'
+Requires-Dist: pyright[nodejs]>=1.1.410; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: python-multipart>=0.0.32; extra == 'dev'
+Requires-Dist: rtoml>=0.13.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.16; extra == 'dev'
+Requires-Dist: textual>=8.2.7; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Requires-Dist: urllib3>=2.7.0; extra == 'dev'
+Requires-Dist: virtualenv>=21.4.2; extra == 'dev'
+Requires-Dist: wheel>=0.47.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
 # lib_shopware6_api_base
 
 <!-- Badges -->
@@ -58,6 +111,9 @@ This is the base abstraction layer. For higher-level functions, see [lib_shopwar
   - [Associations](#associations)
 - [CLI Usage](#cli-usage)
 - [Installation](#installation)
+- [Development](#development)
+  - [Running tests](#running-tests)
+  - [Integration tests](#integration-tests)
 - [Requirements](#requirements)
 - [Changelog](CHANGELOG.md)
 - [License](#license)
@@ -102,17 +158,17 @@ SHOPWARE_STORE_API_SW_ACCESS_KEY="SWSCXXXXXXXXXXXXXXXXXX"
 
 All environment variables use the `SHOPWARE_` prefix to avoid collision with system variables.
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `SHOPWARE_ADMIN_API_URL` | Admin API endpoint | `https://shop.example.com/api` |
-| `SHOPWARE_STOREFRONT_API_URL` | Storefront API endpoint | `https://shop.example.com/store-api` |
-| `SHOPWARE_INSECURE_TRANSPORT` | Allow HTTP (dev only) | `0` (production) or `1` (dev) |
-| `SHOPWARE_USERNAME` | Admin user email | `admin@example.com` |
-| `SHOPWARE_PASSWORD` | Admin user password | `secret` |
+| Variable | Description                                                   | Example |
+|----------|---------------------------------------------------------------|---------|
+| `SHOPWARE_ADMIN_API_URL` | Admin API endpoint                                            | `https://shop.example.com/api` |
+| `SHOPWARE_STOREFRONT_API_URL` | Storefront API endpoint                                       | `https://shop.example.com/store-api` |
+| `SHOPWARE_INSECURE_TRANSPORT` | Allow HTTP (dev only)                                         | `0` (production) or `1` (dev) |
+| `SHOPWARE_USERNAME` | Admin user email                                              | `admin@example.com` |
+| `SHOPWARE_PASSWORD` | Admin user password                                           | `secret` |
 | `SHOPWARE_CLIENT_ID` | Integration Access ID | `SWIA...` |
-| `SHOPWARE_CLIENT_SECRET` | Integration Secret | `...` |
-| `SHOPWARE_GRANT_TYPE` | Auth method | `USER_CREDENTIALS` or `RESOURCE_OWNER` |
-| `SHOPWARE_STORE_API_SW_ACCESS_KEY` | Storefront access key | `SWSC...` |
+| `SHOPWARE_CLIENT_SECRET` | Integration Secret                                            | `...` |
+| `SHOPWARE_GRANT_TYPE` | Auth method                                                   | `USER_CREDENTIALS` or `RESOURCE_OWNER` |
+| `SHOPWARE_STORE_API_SW_ACCESS_KEY` | Storefront access key                                         | `SWSC...` |
 
 ### Loading Configuration
 
@@ -434,6 +490,52 @@ pip install lib_shopware6_api_base
 
 ---
 
+## Development
+
+Project automation runs through a `Makefile` that delegates to [`bmk`](https://pypi.org/project/bmk/)
+(installed automatically as a persistent `uv` tool on first use). Run `make help` to list all targets.
+
+### Running tests
+
+```bash
+make test               # lint (ruff), type-check (pyright), import-linter,
+                        # bandit, pip-audit, and the unit test suite with coverage
+make testintegration    # integration tests only (see prerequisites below)
+```
+
+`make test` runs the full quality gate but **excludes** the integration tests
+(`pytest -m "not integration"`). `make testintegration` runs **only** the
+integration suite (`pytest -m integration`).
+
+### Integration tests
+
+The integration tests exercise the Admin and Storefront clients against a real
+Shopware instance using the [dockware](https://developer.shopware.com/docs/guides/installation/dockware)
+container. The test harness starts and stops the container automatically — no
+manual setup or credentials are required (`tests/docker.env` ships the dockware
+defaults).
+
+Prerequisites:
+
+- **Docker** installed and running, with a **Linux** container engine
+  (`docker info --format '{{.OSType}}'` → `linux`). If Docker is unavailable or
+  not Linux, the integration tests are **skipped** (not failed).
+- **Port 80** free — the container is published on `-p 80:80`.
+- First run pulls `dockware/dev:latest` (a few GB), so it takes a while.
+
+Tip: for fast repeated runs, start the container once and leave it up — the
+harness reuses a running container (and only tears down one it started itself):
+
+```bash
+docker run -d --rm -p 80:80 --name dockware dockware/dev:latest
+make testintegration    # reuses the running container, finishes in seconds
+```
+
+CI runs the unit and integration suites as separate jobs across Linux, macOS,
+and Windows for Python 3.10–3.14.
+
+---
+
 ## Requirements
 
 Automatically installed dependencies:

lib_shopware6_api_base-3.1.0/PKG-INFO → lib_shopware6_api_base-3.1.2/README.md

@@ -1,56 +1,3 @@
-Metadata-Version: 2.4
-Name: lib_shopware6_api_base
-Version: 3.1.0
-Summary: python3 base API client for shopware6
-Project-URL: Homepage, https://github.com/bitranox/lib_shopware6_api_base
-Project-URL: Documentation, https://github.com/bitranox/lib_shopware6_api_base/blob/master/README.md
-Project-URL: Repository, https://github.com/bitranox/lib_shopware6_api_base.git
-Project-URL: Changelog, https://github.com/bitranox/lib_shopware6_api_base/blob/master/CHANGELOG.md
-Author-email: bitranox <bitranox@gmail.com>
-License: MIT
-License-File: LICENSE
-Keywords: api,shopware
-Classifier: Environment :: Console
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: httpx2>=2.2.0
-Requires-Dist: lib-cli-exit-tools>=2.2.4
-Requires-Dist: orjson
-Requires-Dist: pydantic-settings>=2.12.0
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: rich-click
-Provides-Extra: dev
-Requires-Dist: bandit>=1.9.3; extra == 'dev'
-Requires-Dist: build>=1.4.0; extra == 'dev'
-Requires-Dist: codecov-cli>=11.2.6; extra == 'dev'
-Requires-Dist: httpx2>=2.2.0; extra == 'dev'
-Requires-Dist: hypothesis>=6.151.4; extra == 'dev'
-Requires-Dist: import-linter>=2.9; extra == 'dev'
-Requires-Dist: jaraco-context>=6.1.0; extra == 'dev'
-Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
-Requires-Dist: pynacl>=1.6.2; extra == 'dev'
-Requires-Dist: pyright[nodejs]>=1.1.408; extra == 'dev'
-Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
-Requires-Dist: pytest>=9.0.2; extra == 'dev'
-Requires-Dist: python-multipart>=0.0.27; extra == 'dev'
-Requires-Dist: rtoml>=0.13.0; extra == 'dev'
-Requires-Dist: ruff>=0.14.14; extra == 'dev'
-Requires-Dist: textual>=7.5.0; extra == 'dev'
-Requires-Dist: twine>=6.2.0; extra == 'dev'
-Requires-Dist: urllib3>=2.6.3; extra == 'dev'
-Requires-Dist: virtualenv>=20.36.1; extra == 'dev'
-Requires-Dist: wheel>=0.46.3; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # lib_shopware6_api_base
 
 <!-- Badges -->
@@ -111,6 +58,9 @@ This is the base abstraction layer. For higher-level functions, see [lib_shopwar
   - [Associations](#associations)
 - [CLI Usage](#cli-usage)
 - [Installation](#installation)
+- [Development](#development)
+  - [Running tests](#running-tests)
+  - [Integration tests](#integration-tests)
 - [Requirements](#requirements)
 - [Changelog](CHANGELOG.md)
 - [License](#license)
@@ -155,17 +105,17 @@ SHOPWARE_STORE_API_SW_ACCESS_KEY="SWSCXXXXXXXXXXXXXXXXXX"
 
 All environment variables use the `SHOPWARE_` prefix to avoid collision with system variables.
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `SHOPWARE_ADMIN_API_URL` | Admin API endpoint | `https://shop.example.com/api` |
-| `SHOPWARE_STOREFRONT_API_URL` | Storefront API endpoint | `https://shop.example.com/store-api` |
-| `SHOPWARE_INSECURE_TRANSPORT` | Allow HTTP (dev only) | `0` (production) or `1` (dev) |
-| `SHOPWARE_USERNAME` | Admin user email | `admin@example.com` |
-| `SHOPWARE_PASSWORD` | Admin user password | `secret` |
+| Variable | Description                                                   | Example |
+|----------|---------------------------------------------------------------|---------|
+| `SHOPWARE_ADMIN_API_URL` | Admin API endpoint                                            | `https://shop.example.com/api` |
+| `SHOPWARE_STOREFRONT_API_URL` | Storefront API endpoint                                       | `https://shop.example.com/store-api` |
+| `SHOPWARE_INSECURE_TRANSPORT` | Allow HTTP (dev only)                                         | `0` (production) or `1` (dev) |
+| `SHOPWARE_USERNAME` | Admin user email                                              | `admin@example.com` |
+| `SHOPWARE_PASSWORD` | Admin user password                                           | `secret` |
 | `SHOPWARE_CLIENT_ID` | Integration Access ID | `SWIA...` |
-| `SHOPWARE_CLIENT_SECRET` | Integration Secret | `...` |
-| `SHOPWARE_GRANT_TYPE` | Auth method | `USER_CREDENTIALS` or `RESOURCE_OWNER` |
-| `SHOPWARE_STORE_API_SW_ACCESS_KEY` | Storefront access key | `SWSC...` |
+| `SHOPWARE_CLIENT_SECRET` | Integration Secret                                            | `...` |
+| `SHOPWARE_GRANT_TYPE` | Auth method                                                   | `USER_CREDENTIALS` or `RESOURCE_OWNER` |
+| `SHOPWARE_STORE_API_SW_ACCESS_KEY` | Storefront access key                                         | `SWSC...` |
 
 ### Loading Configuration
 
@@ -487,6 +437,52 @@ pip install lib_shopware6_api_base
 
 ---
 
+## Development
+
+Project automation runs through a `Makefile` that delegates to [`bmk`](https://pypi.org/project/bmk/)
+(installed automatically as a persistent `uv` tool on first use). Run `make help` to list all targets.
+
+### Running tests
+
+```bash
+make test               # lint (ruff), type-check (pyright), import-linter,
+                        # bandit, pip-audit, and the unit test suite with coverage
+make testintegration    # integration tests only (see prerequisites below)
+```
+
+`make test` runs the full quality gate but **excludes** the integration tests
+(`pytest -m "not integration"`). `make testintegration` runs **only** the
+integration suite (`pytest -m integration`).
+
+### Integration tests
+
+The integration tests exercise the Admin and Storefront clients against a real
+Shopware instance using the [dockware](https://developer.shopware.com/docs/guides/installation/dockware)
+container. The test harness starts and stops the container automatically — no
+manual setup or credentials are required (`tests/docker.env` ships the dockware
+defaults).
+
+Prerequisites:
+
+- **Docker** installed and running, with a **Linux** container engine
+  (`docker info --format '{{.OSType}}'` → `linux`). If Docker is unavailable or
+  not Linux, the integration tests are **skipped** (not failed).
+- **Port 80** free — the container is published on `-p 80:80`.
+- First run pulls `dockware/dev:latest` (a few GB), so it takes a while.
+
+Tip: for fast repeated runs, start the container once and leave it up — the
+harness reuses a running container (and only tears down one it started itself):
+
+```bash
+docker run -d --rm -p 80:80 --name dockware dockware/dev:latest
+make testintegration    # reuses the running container, finishes in seconds
+```
+
+CI runs the unit and integration suites as separate jobs across Linux, macOS,
+and Windows for Python 3.10–3.14.
+
+---
+
 ## Requirements
 
 Automatically installed dependencies: