chore: Enhance documentation for E2E testing:

- Added clarity and structure to README files, including recent updates and getting started sections.
- Improved manual verification documentation for CrowdSec authentication, emphasizing expected outputs and success criteria.
- Updated debugging guide with detailed output examples and automatic trace capture information.
- Refined best practices for E2E tests, focusing on efficient polling, locator strategies, and state management.
- Documented triage report for DNS Provider feature tests, highlighting issues fixed and test results before and after improvements.
- Revised E2E test writing guide to include when to use specific helper functions and patterns for better test reliability.
- Enhanced troubleshooting documentation with clear resolutions for common issues, including timeout and token configuration problems.
- Updated tests README to provide quick links and best practices for writing robust tests.

docs/analysis/crowdsec_integration_failure_analysis.md

@@ -2,7 +2,7 @@
 
 **Date:** 2026-01-28
 **PR:** #550 - Alpine to Debian Trixie Migration
-**CI Run:** https://github.com/Wikid82/Charon/actions/runs/21456678628/job/61799104804
+**CI Run:** <https://github.com/Wikid82/Charon/actions/runs/21456678628/job/61799104804>
 **Branch:** feature/beta-release
 
 ---
@@ -18,16 +18,19 @@ The CrowdSec integration tests are failing after migrating the Dockerfile from A
 ### 1. **CrowdSec Builder Stage Compatibility**
 
 **Alpine vs Debian Differences:**
+
 - **Alpine** uses `musl libc`, **Debian** uses `glibc`
 - Different package managers: `apk` (Alpine) vs `apt` (Debian)
 - Different package names and availability
 
 **Current Dockerfile (lines 218-270):**
+
 ```dockerfile
 FROM --platform=$BUILDPLATFORM golang:1.25.7-trixie AS crowdsec-builder
 ```
 
 **Dependencies Installed:**
+
 ```dockerfile
 RUN apt-get update && apt-get install -y --no-install-recommends \
     git clang lld \
@@ -36,6 +39,7 @@ RUN xx-apt install -y gcc libc6-dev
 ```
 
 **Possible Issues:**
+
 - **Missing build dependencies**: CrowdSec might require additional packages on Debian that were implicitly available on Alpine
 - **Git clone failures**: Network issues or GitHub rate limiting
 - **Dependency resolution**: `go mod tidy` might behave differently
@@ -44,6 +48,7 @@ RUN xx-apt install -y gcc libc6-dev
 ### 2. **CrowdSec Binary Path Issues**
 
 **Runtime Image (lines 359-365):**
+
 ```dockerfile
 # Copy CrowdSec binaries from the crowdsec-builder stage (built with Go 1.25.5+)
 COPY --from=crowdsec-builder /crowdsec-out/crowdsec /usr/local/bin/crowdsec
@@ -52,17 +57,20 @@ COPY --from=crowdsec-builder /crowdsec-out/config /etc/crowdsec.dist
 ```
 
 **Possible Issues:**
+
 - If the builder stage fails, these COPY commands will fail
 - If fallback stage is used (for non-amd64), paths might be wrong
 
 ### 3. **CrowdSec Configuration Issues**
 
 **Entrypoint Script CrowdSec Init (docker-entrypoint.sh):**
+
 - Symlink creation from `/etc/crowdsec` to `/app/data/crowdsec/config`
 - Configuration file generation and substitution
 - Hub index updates
 
 **Possible Issues:**
+
 - Symlink already exists as directory instead of symlink
 - Permission issues with non-root user
 - Configuration templates missing or incompatible
@@ -70,12 +78,14 @@ COPY --from=crowdsec-builder /crowdsec-out/config /etc/crowdsec.dist
 ### 4. **Test Script Environment Issues**
 
 **Integration Test (crowdsec_integration.sh):**
+
 - Builds the image with `docker build -t charon:local .`
 - Starts container and waits for API
 - Tests CrowdSec Hub connectivity
 - Tests preset pull/apply functionality
 
 **Possible Issues:**
+
 - Build step timing out or failing silently
 - Container failing to start properly
 - CrowdSec processes not starting
@@ -88,6 +98,7 @@ COPY --from=crowdsec-builder /crowdsec-out/config /etc/crowdsec.dist
 ### Step 1: Check Build Logs
 
 Review the CI build logs for the CrowdSec builder stage:
+
 - Look for `git clone` errors
 - Check for `go get` or `go mod tidy` failures
 - Verify `xx-go build` completes successfully
@@ -96,6 +107,7 @@ Review the CI build logs for the CrowdSec builder stage:
 ### Step 2: Verify CrowdSec Binaries
 
 Check if CrowdSec binaries are actually present:
+
 ```bash
 docker run --rm charon:local which crowdsec
 docker run --rm charon:local which cscli
@@ -105,6 +117,7 @@ docker run --rm charon:local cscli version
 ### Step 3: Check CrowdSec Configuration
 
 Verify configuration is properly initialized:
+
 ```bash
 docker run --rm charon:local ls -la /etc/crowdsec
 docker run --rm charon:local ls -la /app/data/crowdsec
@@ -114,6 +127,7 @@ docker run --rm charon:local cat /etc/crowdsec/config.yaml
 ### Step 4: Test CrowdSec Locally
 
 Run the integration test locally:
+
 ```bash
 # Build image
 docker build --no-cache -t charon:local .
@@ -129,6 +143,7 @@ docker build --no-cache -t charon:local .
 ### Fix 1: Add Missing Build Dependencies
 
 If the build is failing due to missing dependencies, add them to the CrowdSec builder:
+
 ```dockerfile
 RUN apt-get update && apt-get install -y --no-install-recommends \
     git clang lld \
@@ -139,6 +154,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 ### Fix 2: Add Build Stage Debugging
 
 Add debugging output to identify where the build fails:
+
 ```dockerfile
 # After git clone
 RUN echo "CrowdSec source cloned successfully" && ls -la
@@ -153,6 +169,7 @@ RUN echo "Build complete" && ls -la /crowdsec-out/
 ### Fix 3: Use CrowdSec Fallback
 
 If the build continues to fail, ensure the fallback stage is working:
+
 ```dockerfile
 # In final stage, use conditional COPY
 COPY --from=crowdsec-fallback /crowdsec-out/bin/crowdsec /usr/local/bin/crowdsec || \
@@ -162,6 +179,7 @@ COPY --from=crowdsec-builder /crowdsec-out/crowdsec /usr/local/bin/crowdsec
 ### Fix 4: Verify cscli Before Test
 
 Add a verification step in the entrypoint:
+
 ```bash
 if ! command -v cscli >/dev/null; then
     echo "ERROR: CrowdSec not installed properly"