Setup Validation

What This Script Does

The validate-setup.ps1 script is a pre-flight and post-flight validation tool for the Chocolatey Scripts toolkit. Its primary purpose is to verify that all the components of the toolkit are correctly installed, that the configuration file is properly formatted with valid values, and that the underlying system meets all the requirements for the scripts to function correctly. Think of it as a checklist inspector that goes through every requirement and dependency, reporting what is in order and what needs attention before you start using the toolkit.

The first major validation phase checks for the presence of all expected script files in the toolkit directory. The script maintains an internal manifest of all the files that should be present in a complete installation, including the main PowerShell scripts, the configuration file, the helper functions, and any supporting files. For each expected file, it verifies that the file exists at the expected path and that it is not empty (a zero-byte file would indicate a corrupted download or incomplete extraction). If any files are missing, the script reports exactly which ones are absent and suggests re-downloading the toolkit from the GitHub repository to obtain the missing files.

The file presence check is particularly valuable after downloading and extracting the toolkit from a ZIP file, which is one of the recommended installation methods. ZIP extraction can sometimes fail silently, producing an incomplete set of files without any error message. Similarly, if you cloned the repository with Git and the clone was interrupted by a network issue, some files might be missing. Running the validation script immediately after downloading the toolkit catches these issues before you discover them the hard way by trying to run a script that depends on a missing file.

The second validation phase performs a thorough examination of the config.json configuration file. This is one of the most important checks because configuration problems are one of the most common sources of issues when running the toolkit scripts, particularly the auto-update script which depends heavily on configuration values. The validation starts by checking that the file exists and that it contains valid JSON syntax. A misplaced comma, missing bracket, or stray character in the JSON file would prevent any script that reads the configuration from functioning, so catching syntax errors early is critical.

Beyond basic JSON syntax validation, the script examines each configuration value for correctness and completeness. It checks that all required keys are present (such as wifiNetwork, emailAddress, smtpServer, and smtpPort) and that their values are of the expected type (strings for text values, integers for port numbers, booleans for notification toggles). The script also performs semantic validation on values where possible. For example, it verifies that the SMTP port number falls within the valid range (1-65535), that the email address contains an @ symbol and a domain, and that the SMTP server name is not empty when email notifications are enabled.

One of the most helpful checks in the configuration validation is the detection of placeholder values. When the toolkit is first downloaded, the config.json file contains placeholder values like "your-wifi-network-name" and "[email protected]" that are meant to be replaced with your actual values. Many users forget to update one or more of these placeholders before running the scripts, which leads to confusing failures. The validation script specifically checks for these known placeholder patterns and flags them with a clear message explaining that the value needs to be replaced with a real value. This check alone prevents one of the most common setup mistakes.

The third validation phase verifies that the system meets all requirements for running the toolkit. This includes checking the Windows version (Windows 10 or 11 required), the PowerShell version (5.1 or later required, 7 or later recommended), the availability of the .NET Framework (required by Chocolatey), and the presence of an internet connection (required for downloading and updating packages). Each requirement is checked independently, and the results are presented in a clear pass/fail format with explanations for any failures.

The system requirements check also looks for optional but recommended components. For example, it checks whether Git is installed (useful for keeping the toolkit updated via repository pulls), whether the Windows Task Scheduler service is running (required for scheduled maintenance tasks), and whether the Chocolatey package manager itself is installed. If Chocolatey is not yet installed, the validation script notes this and recommends running install-chocolatey.ps1 as the first step. If Chocolatey is installed, it additionally checks the version and reports whether an update is available.

An important design characteristic of this script is that it does not require Administrator privileges to run. While many other scripts in the toolkit need elevated permissions for installing packages or modifying system settings, the validation script is purely diagnostic and only reads information. This means you can run it at any time from a regular (non-elevated) PowerShell window to check the state of your installation. The script does note in its output that some toolkit scripts will require Administrator privileges when you actually run them, but the validation itself operates entirely in read-only mode.

The script provides clear, structured output organized into sections for each validation phase. Each check is presented with a status indicator (PASS, WARN, or FAIL), the name of the check, and a description of the result. Warning status is used for issues that will not prevent the toolkit from functioning but should be addressed for optimal operation, such as having an older version of PowerShell or missing optional components. Failed status is used for issues that will prevent one or more scripts from functioning correctly and must be resolved before proceeding.

At the end of the validation, the script provides a summary with an overall assessment and prioritized setup recommendations. If everything passes, the summary confirms that the toolkit is ready to use and suggests starting with install-chocolatey.ps1 if Chocolatey is not yet installed, or health-check.ps1 if it is. If there are failures, the summary lists the issues in priority order with specific remediation steps for each one. This prioritized approach ensures that users address the most critical issues first rather than getting stuck on optional improvements while critical prerequisites remain unmet.

The validation script is recommended to be run in two scenarios. First, run it immediately after downloading or cloning the toolkit to verify that all files are present and the configuration is ready. Second, run it any time you experience unexpected behavior from any of the toolkit scripts, as the validation may reveal a configuration or environmental issue that explains the problem. Some users also include the validation script in their periodic maintenance routine alongside the health check, running both monthly to ensure everything remains in good order.

Usage

The validation script does not require Administrator privileges and can be run from any PowerShell window.

# Run setup validation
.\validate-setup.ps1

Example output from the validation script:

========================================
  Chocolatey Scripts Setup Validation
========================================

--- File Checks ---
[PASS] install-chocolatey.ps1
[PASS] install-essential-apps.ps1
[PASS] auto-update-chocolatey.ps1
[PASS] cleanup-chocolatey.ps1
[PASS] health-check.ps1
[PASS] backup-packages.ps1
[PASS] setup-scheduled-tasks.ps1
[PASS] Send-ToastNotification.ps1
[PASS] validate-setup.ps1
[PASS] config.json

--- Configuration Checks ---
[PASS] config.json syntax valid
[PASS] wifiNetwork configured
[WARN] emailAddress contains placeholder value
[PASS] smtpPort valid (587)
[PASS] notifications.toast enabled
[WARN] notifications.email enabled but email not configured

--- System Requirements ---
[PASS] Windows 11 23H2
[PASS] PowerShell 7.4.1
[PASS] .NET Framework 4.8.1
[PASS] Internet connection available
[PASS] Chocolatey installed (v2.4.1)
[PASS] Git installed (v2.43.0)
[PASS] Task Scheduler service running

--- Summary ---
Status: READY (2 warnings)
Recommendations:
  1. Update emailAddress in config.json with your email
  2. Update smtpServer in config.json if you want email reports

What Gets Changed

• No system modifications — This script is completely read-only and does not modify any files, settings, or configurations on your system.
• No Administrator required — The script runs entirely in user-level mode and does not need elevated privileges.
• Console output — Displays a formatted validation report in the PowerShell window.

Related Scripts