[WIP] Fix resturn types br

.ansible-lint

@@ -2,6 +2,10 @@
 profile: production
 exclude_paths:
   - 'changelogs/'
-parseable: true
+  # Molecule inventory files are dicts, not playbooks; avoid syntax-check playbook rule
+  - 'extensions/molecule/default/inventory.yml'
+  - 'extensions/molecule/inventory.yml'
+  - 'extensions/molecule/organization_mock/inventory.yml'
+  - 'extensions/molecule/users_mock/inventory.yml'
 use_default_rules: true
 ...

.github/workflows/integration.yml

@@ -15,12 +15,20 @@ env:
   ANSIBLE_FORCE_COLOR: '1'
 jobs:
   integration:
-    name: collection integration test
+    name: integration (${{ matrix.connection_mode }})
     runs-on: ubuntu-latest
     environment: CI
     env:
       HEADLESS: "yes"
 
+    strategy:
+      fail-fast: false
+      matrix:
+        connection_mode:
+          - local
+          - http-direct
+          - http-persistent
+
     steps:
       - uses: actions/checkout@v3
         with:
@@ -56,8 +64,19 @@ jobs:
             echo "GATEWAY_PASSWORD=$ADMIN_PW" >> $GITHUB_ENV
         working-directory: aap-gateway
 
-      - name: Perform integration tests
-        run: make collection-test
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install integration controller requirements
+        run: pip install -r tests/integration/requirements.txt ansible-core
+        working-directory: ansible-platform
+
+      - name: Perform integration tests (${{ matrix.connection_mode }})
+        env:
+          ANSIBLE_TEST_INTEGRATION_NO_VENV: '1'
+        run: make collection-test CONNECTION_MODE=${{ matrix.connection_mode }}
         working-directory: ansible-platform
 
       - name: Dump the container logs on failure

.github/workflows/linting.yml

@@ -6,7 +6,7 @@ env:
 on:
   pull_request:
   push:
-    branches: [devel]
+    branches: [devel, ANSTRAT-1640]
 jobs:
   common-tests:
     name: ${{ matrix.tests.name }}
@@ -18,12 +18,12 @@ jobs:
       fail-fast: false
       matrix:
         tests:
-          - name: flake8
-            command: check_flake8
-          - name: black
-            command: check_black
-          - name: isort
-            command: check_isort
+          - name: ruff
+            command: check_ruff
+          - name: mypy
+            command: check_mypy
+          - name: pydoclint
+            command: check_pydoclint
     steps:
       - name: Install make
         run: sudo apt install make

.github/workflows/molecule-mock.yml

@@ -0,0 +1,84 @@
+---
+# Run all Molecule *_mock scenarios against the mock Gateway (no real AAP).
+# Each scenario spins up its own mock server, runs converge → verify → cleanup,
+# then tears down — fully parallel and independent.
+#
+# New module scenarios are picked up automatically: add an extensions/molecule/*_mock/
+# directory with converge.yml + verify.yml and this workflow runs it on the next PR.
+name: molecule (mock)
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+  push:
+    branches: [devel, ANSTRAT-1640]
+
+env:
+  ANSIBLE_FORCE_COLOR: "1"
+  PY_COLORS: "1"
+
+jobs:
+  # ── Discover all *_mock scenarios ──────────────────────────────────────────
+  list-scenarios:
+    name: Discover mock scenarios
+    runs-on: ubuntu-latest
+    outputs:
+      scenarios: ${{ steps.list.outputs.scenarios }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: List *_mock scenario directories
+        id: list
+        run: |
+          scenarios=$(ls extensions/molecule/ | grep '_mock$' | jq -R . | jq -sc .)
+          echo "scenarios=$scenarios" >> "$GITHUB_OUTPUT"
+          echo "Found scenarios: $scenarios"
+
+  # ── Run each scenario in parallel, each with its own mock server ────────────
+  molecule-mock:
+    name: Molecule (${{ matrix.scenario }})
+    needs: list-scenarios
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        scenario: ${{ fromJson(needs.list-scenarios.outputs.scenarios) }}
+    env:
+      # galaxy install puts the collection here; keeps Molecule's collections_path resolvable
+      ANSIBLE_COLLECTIONS_PATH: $HOME/.ansible/collections
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ansible-core, molecule, and collection runtime deps
+        run: pip install ansible-core molecule requests
+
+      - name: Install collection
+        run: ansible-galaxy collection install . --force
+
+      - name: Start mock Gateway (default scenario)
+        run: molecule create -s default
+
+      - name: Wait for mock Gateway health endpoint
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf http://127.0.0.1:8000/health && break
+            echo "Waiting for mock ($i/30)..."
+            sleep 2
+          done
+          curl -sf http://127.0.0.1:8000/health
+
+      - name: Run ${{ matrix.scenario }}
+        run: molecule test -s ${{ matrix.scenario }} --all
+
+      - name: Stop mock Gateway
+        if: always()
+        run: molecule destroy -s default
+...

.github/workflows/unit.yml

@@ -0,0 +1,40 @@
+---
+name: unit tests
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+  push:
+    branches: [devel, ANSTRAT-1640]
+
+env:
+  LC_ALL: "C.UTF-8"
+
+jobs:
+  unit:
+    name: Unit (pytest)
+    runs-on: ubuntu-latest
+    steps:
+      # Check out into ansible_collections/ansible/platform/ so that
+      # "import ansible_collections.ansible.platform.*" resolves correctly.
+      # conftest.py walks up 4 levels from the collection root to reach the
+      # workspace root (which contains ansible_collections/), matching the
+      # same structure used in local development.
+      - uses: actions/checkout@v4
+        with:
+          path: ansible_collections/ansible/platform
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: python -m pip install ansible-core pytest
+
+      - name: Run unit tests
+        working-directory: ansible_collections/ansible/platform
+        run: python -m pytest tests/unit/ -v
+...

.gitignore

@@ -88,6 +88,7 @@ celerybeat-schedule
 # Environments
 .env
 .venv
+.venv-unit
 env/
 venv/
 ENV/
@@ -113,3 +114,6 @@ venv.bak/
 .DS_Store
 
 changelogs/.plugin-cache.yaml
+
+# Integration test config (contains gateway password)
+tests/integration/integration_config.yml

Makefile

@@ -12,9 +12,13 @@ PYTHON_VERSION:
 	@echo "$(subst python,,$(PYTHON))"
 
 .PHONY: PYTHON_VERSION clean git_hooks_config \
+	check_ruff check_mypy check_pydoclint \
 	collection-install collection-test collection-docs \
 	collection-lint collection-sanity  collection-test-completeness \
-	collection-test-integration-check
+	collection-test-integration-check \
+	collection-test-local collection-test-http-direct collection-test-http-persistent \
+	collection-test-all-connections \
+	molecule-test molecule-test-all
 
 ## Set the local git configuration(specific to this repo) to look for hooks in .githooks folder
 git_hooks_config:
@@ -26,17 +30,17 @@ clean:
 	@-find . -type d -name "__pycache__" -print0 \
 			 -o -type d -name ".pytest_cache" -print0 | xargs -0 $(RM) -rf
 
-## Run black syntax check
-check_black:
-	tox -e black -- --check $(CHECK_SYNTAX_FILES)
+## Run ruff lint and format check (replaces flake8, black, isort)
+check_ruff:
+	tox -e ruff
 
-## Run flake8 syntax check
-check_flake8:
-	tox -e flake8 -- $(CHECK_SYNTAX_FILES)
+## Run mypy static type check
+check_mypy:
+	tox -e mypy
 
-## Run isort syntax check
-check_isort:
-	tox -e isort -- --check $(CHECK_SYNTAX_FILES)
+## Run pydoclint docstring style check
+check_pydoclint:
+	tox -e pydoclint
 
 ## Install the collection locally on your machine
 collection-install:
@@ -70,11 +74,57 @@ collection-lint: collection-install
 
 ## Run the collection tests
 ## Requires the GATEWAY_PASSWORD env variable to be set
-collection-test: collection-install
-	echo 'gateway_password: $(GATEWAY_PASSWORD)' > /tmp/collections/ansible_collections/ansible/platform/tests/integration/integration_config.yml && \
-	cat /tmp/collections/ansible_collections/ansible/platform/tests/integration/integration_config.yml && \
+## Set ANSIBLE_TEST_INTEGRATION_NO_VENV=1 to run without --venv (e.g. in CI after installing controller deps)
+## Set CONNECTION_MODE to control which connection mode is tested:
+##   local            (default) – ephemeral DirectHTTPClient, one per task
+##   http-direct      – ansible.platform.http plugin, DirectHTTPClient, one per task
+##   http-persistent  – ansible.platform.http plugin, shared ManagerRPCClient process
+ANSIBLE_TEST_INTEGRATION_VENV := --venv
+ifneq ($(ANSIBLE_TEST_INTEGRATION_NO_VENV),)
+ANSIBLE_TEST_INTEGRATION_VENV :=
+endif
+CONNECTION_MODE ?= local
+
+_write_integration_config:
+	@mkdir -p /tmp/collections/ansible_collections/ansible/platform/tests/integration
+	@printf 'gateway_password: %s\nconnection_mode: %s\n' \
+		'$(GATEWAY_PASSWORD)' '$(CONNECTION_MODE)' \
+		> /tmp/collections/ansible_collections/ansible/platform/tests/integration/integration_config.yml
+	@cat /tmp/collections/ansible_collections/ansible/platform/tests/integration/integration_config.yml
+
+collection-test: collection-install _write_integration_config
 	cd /tmp/collections/ansible_collections/ansible/platform && \
-	  ansible-test integration --color yes --venv --requirements --coverage
+	  ansible-test integration --color yes $(ANSIBLE_TEST_INTEGRATION_VENV) --requirements --coverage
+
+## Run integration tests explicitly using connection: local (default ephemeral mode)
+collection-test-local: collection-install
+	$(MAKE) collection-test CONNECTION_MODE=local
+
+## Run integration tests using connection: ansible.platform.http in direct (non-persistent) mode
+collection-test-http-direct: collection-install
+	$(MAKE) collection-test CONNECTION_MODE=http-direct
+
+## Run integration tests using connection: ansible.platform.http in persistent manager mode
+collection-test-http-persistent: collection-install
+	$(MAKE) collection-test CONNECTION_MODE=http-persistent
+
+## Run integration tests sequentially for all three connection modes
+collection-test-all-connections: collection-install
+	$(MAKE) collection-test CONNECTION_MODE=local
+	$(MAKE) collection-test CONNECTION_MODE=http-direct
+	$(MAKE) collection-test CONNECTION_MODE=http-persistent
+
+## Run a single Molecule scenario (mock tests, no real Gateway needed).
+## Usage: make molecule-test SCENARIO=role_user_assignment_mock
+##        make molecule-test SCENARIO=users_mock
+## Runs from inside the scenario directory so molecule finds molecule.yml regardless of version.
+SCENARIO ?= default
+molecule-test:
+	cd extensions/molecule/$(SCENARIO) && molecule test
+
+## Run all Molecule mock scenarios (starts mock server via default scenario, runs all, tears down).
+molecule-test-all:
+	cd extensions && molecule test --all
 
 ## Run the collections test-integration check to see if all modules have integration tests
 collection-test-integration-check:

conftest.py

@@ -0,0 +1,19 @@
+# (c) 2026 Red Hat Inc.
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""Root conftest — ensure ansible_collections parent directory is on sys.path.
+
+This allows ``import ansible_collections.ansible.platform.*`` to work when
+running pytest directly from the collection root:
+
+    pytest tests/unit/ -v
+"""
+
+import sys
+from pathlib import Path
+
+# conftest.py lives at ansible_collections/ansible/platform/conftest.py
+# Go up 4 levels to reach the parent of ansible_collections/
+_workspace_root = str(Path(__file__).resolve().parent.parent.parent.parent)
+if _workspace_root not in sys.path:
+    sys.path.insert(0, _workspace_root)