Setup Instructions

Installation and Environment Configuration Guide

The following steps provide both automated and manual installation options for setting up the automation framework environment. The automated approach uses the Automation-BSH-AutoTools repository for streamlined setup.

ℹ️ Platform Note

This guide is designed primarily for macOS with Apple Silicon (M1/M2/M3) processors but is adaptable to other platforms.

Prerequisites ?

Hardware Requirements

Component	Minimum	Recommended
Processor	Apple Silicon (M1) or Intel	Apple Silicon (M2/M3)
Memory	8GB RAM	16GB RAM
Storage	10GB free disk space	20GB+ free disk space

Software Requirements

Operating System: macOS 15.x (Sequoia) or greater
Administrator Access: Required for tool installation

Automated Installation RECOMMENDED ?

The AutoTools script handles the complete environment setup automatically.

Step 1: Create Project Directory Structure

Ensure the Automation-Projects directory exists:

Create directory structure

mkdir -p ~/Documents/Development/Automation/Automation-Projects

Step 2: Clone AutoTools Repository

Clone the Automation-BSH-AutoTools repository:

Clone AutoTools

git clone git@github.com:MurahoTech/Automation-BSH-AutoTools.git \
    ~/Documents/Development/Automation/Automation-Projects/Automation-BSH-AutoTools

Step 3: Launch AutoTools

Execute the AutoTools setup script:

Run AutoTools

~/Documents/Development/Automation/Automation-Projects/Automation-BSH-AutoTools/autotools.sh

What AutoTools Installs

The automated script will install and configure:

Tool	Purpose
Homebrew ?	Package manager for macOS
Git	Version control system
Java 23 ?	OpenJDK via Homebrew
Maven ?	Build and dependency management
Chrome	Browser for test execution
ChromeDriver ?	WebDriver for Chrome automation
Allure ?	Test reporting framework
VSCode	Recommended IDE with extensions

Manual Installation ?

If you prefer manual installation or need to troubleshoot, follow these steps:

1. Install Homebrew

Install Homebrew package manager

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Java 23

Install and link OpenJDK 23

brew install openjdk@23
brew link --force openjdk@23

Verify installation:

Verify Java version

java -version

3. Install Maven

Install Maven

brew install maven

Verify installation:

Verify Maven version

mvn -version

4. Install Git

Install Git

brew install git

Configure Git with your credentials:

Configure Git user

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

5. Install Chrome Browser

Download from Google Chrome or via Homebrew:

Install Chrome via Homebrew

brew install --cask google-chrome

6. Install Allure Report

Install Allure

brew install allure

7. Install VSCode (Optional but Recommended)

Install Visual Studio Code

brew install --cask visual-studio-code

Project Setup

1. Clone the Test Automation Project

Clone your project

cd ~/Documents/Development/Automation/Automation-Projects
git clone [your-automation-project-repository]

2. Install Maven Dependencies

Navigate to project directory and run:

Install dependencies (skip tests for speed)

mvn clean install -DskipTests

3. Verify Setup

Run a simple test to verify everything is working:

Run verification test

mvn test -Dtest=TS_Authentication_JUnit#testValidLogin

Environment Variables ?

Add these to your ~/.zshrc or ~/.bash_profile:

# Java Home
export JAVA_HOME=/opt/homebrew/opt/openjdk@23
export PATH="$JAVA_HOME/bin:$PATH"

# Maven Options
export MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m"

# Chrome Driver (if manually installed)
export PATH="/usr/local/bin/chromedriver:$PATH"

Reload your shell configuration:

Reload shell configuration

source ~/.zshrc

Verification Checklist

✅ Setup Verification

Java 23 installed and accessible
Maven installed and configured
Git installed and configured
Chrome browser installed
Project cloned successfully
Maven dependencies downloaded
Sample test executes successfully
Allure report generates properly

Troubleshooting

Common Issues

⚠️ Java Version Mismatch

Ensure Java 23 is the active version. Use java -version to verify. If another version is active, check your JAVA_HOME environment variable.

⚠️ Maven Build Failures

Clear Maven cache and retry:

Clear Maven cache

rm -rf ~/.m2/repository
mvn clean install

⚠️ ChromeDriver Issues

Ensure Chrome browser is up to date. ChromeDriver version must match your Chrome browser version. The framework uses WebDriverManager to handle this automatically in most cases.

⚠️ Permission Errors

You may need to allow apps in System Preferences → Security & Privacy. macOS Gatekeeper sometimes blocks unsigned binaries like ChromeDriver.

Next Steps

Once your environment is set up, explore these framework capabilities:

Document	Description
Framework Overview	Architecture and components
Test Development	Writing tests with Page Object Model
Test Execution	Running tests and generating reports
Architecture Diagrams	Visual understanding of framework design
HTTP Security Assessment	Automated security audits
Network Diagnostics	Connectivity and performance testing
mAi Advisor™	Intelligent recommendations

Support

For additional help:

Check project README.md
Review API Documentation (run mvn site first)
Contact framework maintainers