From d03900c0e82b183e4dbe0c9b4e9ad301f825bf23 Mon Sep 17 00:00:00 2001
From: David <dgx.arnold@gmail.com>
Date: Fri, 4 Oct 2024 11:11:55 +0200
Subject: [PATCH] ci: add description to ci helper script

---
 .github/helper/ci.py | 68 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 64 insertions(+), 4 deletions(-)

diff --git a/.github/helper/ci.py b/.github/helper/ci.py
index 2d25f1d377..165c1b6a7d 100644
--- a/.github/helper/ci.py
+++ b/.github/helper/ci.py
@@ -1,9 +1,29 @@
+"""
+Code Coverage and Parallel Test Runner Script
+
+This script is designed to run parallel tests for Frappe applications with optional code coverage.
+It sets up the test environment, handles code coverage configuration, and executes tests using
+either a local parallel test runner or an orchestrator-based runner.
+
+Key features:
+- Configurable code coverage for specific apps
+- Support for local parallel testing and orchestrator-based testing
+- Customizable inclusion and exclusion patterns for coverage
+- Environment variable based configuration
+
+Usage:
+This script is typically run as part of a CI/CD pipeline or for local development testing.
+It can be configured using environment variables such as SITE, ORCHESTRATOR_URL, WITH_COVERAGE, etc.
+"""
+
 # Copyright (c) 2022, Frappe Technologies Pvt. Ltd. and Contributors
 # MIT License. See LICENSE
+
 import json
 import os
 from pathlib import Path
 
+# Define standard patterns for file inclusions and exclusions in coverage
 STANDARD_INCLUSIONS = ["*.py"]
 
 STANDARD_EXCLUSIONS = [
@@ -22,7 +42,7 @@ STANDARD_EXCLUSIONS = [
 	".github/*",
 ]
 
-# tested via commands' test suite
+# Files that are tested via command line interface
 TESTED_VIA_CLI = [
 	"*/frappe/installer.py",
 	"*/frappe/utils/install.py",
@@ -34,14 +54,36 @@ TESTED_VIA_CLI = [
 	"*/frappe/database/**/setup_db.py",
 ]
 
-FRAPPE_EXCLUSIONS = ["*/tests/*", "*/commands/*", "*/frappe/change_log/*", "*/frappe/exceptions*", "*/frappe/desk/page/setup_wizard/setup_wizard.py", "*/frappe/coverage.py", "*frappe/setup.py", "*/frappe/hooks.py", "*/doctype/*/*_dashboard.py", "*/patches/*", "*/.github/helper/ci.py", *TESTED_VIA_CLI]
+# Additional exclusions specific to the Frappe app
+FRAPPE_EXCLUSIONS = [
+	"*/tests/*",
+	"*/commands/*",
+	"*/frappe/change_log/*",
+	"*/frappe/exceptions*",
+	"*/frappe/desk/page/setup_wizard/setup_wizard.py",
+	"*/frappe/coverage.py",
+	"*frappe/setup.py",
+	"*/frappe/hooks.py",
+	"*/doctype/*/*_dashboard.py",
+	"*/patches/*",
+	"*/.github/helper/ci.py",
+	*TESTED_VIA_CLI,
+]
 
 
 def get_bench_path():
+	"""Get the path to the bench directory."""
 	return Path(__file__).resolve().parents[4]
 
 
 class CodeCoverage:
+	"""
+	Context manager for handling code coverage.
+
+	This class sets up code coverage measurement for a specific app,
+	applying the appropriate inclusion and exclusion patterns.
+	"""
+
 	def __init__(self, with_coverage, app):
 		self.with_coverage = with_coverage
 		self.app = app or "frappe"
@@ -49,10 +91,9 @@ class CodeCoverage:
 	def __enter__(self):
 		if self.with_coverage:
 			import os
-
 			from coverage import Coverage
 
-			# Generate coverage report only for app that is being tested
+			# Set up coverage for the specific app
 			source_path = os.path.join(get_bench_path(), "apps", self.app)
 			print(f"Source path: {source_path}")
 			omit = STANDARD_EXCLUSIONS[:]
@@ -71,6 +112,7 @@ class CodeCoverage:
 
 
 if __name__ == "__main__":
+	# Configuration
 	app = "frappe"
 	site = os.environ.get("SITE") or "test_site"
 	use_orchestrator = bool(os.environ.get("ORCHESTRATOR_URL"))
@@ -78,6 +120,7 @@ if __name__ == "__main__":
 	build_number = 1
 	total_builds = 1
 
+	# Parse build information from environment variables
 	try:
 		build_number = int(os.environ.get("BUILD_NUMBER"))
 	except Exception:
@@ -88,7 +131,24 @@ if __name__ == "__main__":
 	except Exception:
 		pass
 
+	# Run tests with code coverage
 	with CodeCoverage(with_coverage=with_coverage, app=app):
+		# Add ASCII banner at the end
+		mode = "Orchestrator" if use_orchestrator else "Parallel"
+		banner = f"""
+		╔{'═' * 50}╗
+		║{' ' * 50}║
+		║     CI Helper Script Execution Summary     ║
+		║{' ' * 50}║
+		╠{'═' * 50}╣
+		║ Mode:         {mode:<29} ║
+		║ App:          {app:<29} ║
+		║ Site:         {site:<29} ║
+		║ Build Number: {build_number:<29} ║
+		║ Total Builds: {total_builds:<29} ║
+		╚{'═' * 50}╝
+		"""
+		print(banner)
 		if use_orchestrator:
 			from frappe.parallel_test_runner import ParallelTestWithOrchestrator