How to Test GhostTrack: Complete Validation Guide for the Python OSINT Tool

Testing GhostTrack involves installing Python dependencies from requirements.txt, executing GhostTR.py, and manually verifying each menu option against known test inputs like 8.8.8.8 for IP tracking or +14155552671 for phone analysis.

GhostTrack by HunxByts is a lightweight Python-based OSINT utility for querying IP addresses, phone numbers, and usernames across social media platforms. Because the tool is implemented as a single interactive script (GhostTR.py), validation relies on manual testing against public APIs to confirm accurate data retrieval and formatting. This guide covers the complete testing workflow, from environment setup to edge-case validation, using the actual source code structure.

Architecture Overview for Testing

Understanding the codebase layout helps target specific functions during validation. The entire application resides in GhostTR.py, which uses a decorator-based menu system to dispatch user choices.

• Entry Point and Imports: Lines 9‑25 load requests and phonenumbers while defining ANSI color constants for terminal output.
• Menu Decoration: The @is_option decorator (lines 29‑37) wraps each feature call with run_banner() to display the ASCII header before execution.
• Core Functions: Four primary features implement the OSINT logic:
  • IP_Track (lines 40‑78): Queries http://ipwho.is/ for geolocation data.
  • showIP (lines 69‑77): Fetches the user's public IP via https://api.ipify.org/.
  • phoneGW (lines 80‑108): Parses international phone numbers using the phonenumbers library.
  • TrackLu (lines 121‑168): Enumerates usernames across approximately 25 social media endpoints.
• Control Flow: The main() loop (lines 156‑169) renders the menu via option_text() and invokes execute_option() to dispatch choices.

This modular structure allows testers to isolate individual components by importing specific functions or by exercising them through the interactive menu.

Environment Setup and Prerequisites

Before testing, verify that Python 3 and Git are available. The repository requires only two external libraries listed in requirements.txt.

Install the dependencies:

git clone https://github.com/HunxByts/GhostTrack.git
cd GhostTrack
pip3 install -r requirements.txt

The requirements.txt file specifies requests for HTTP operations and phonenumbers for telecom data parsing. Once installed, launch the tool to confirm the environment loads correctly:

python3 GhostTR.py

You should see the stylized banner followed by the numbered menu:

[ 1 ] IP Tracker
[ 2 ] Show Your IP
[ 3 ] Phone Number Tracker
[ 4 ] Username Tracker
[ 0 ] Exit

Step-by-Step Functional Testing

Testing the IP Tracker (Option 1)

Select option 1 to test the IP_Track function. When prompted, enter a known public IP address such as 8.8.8.8 (Google DNS).

The script constructs a request to http://ipwho.is/8.8.8.8 and parses the JSON response. Verify that the terminal output matches the API fields:

• Country: United States
• City: Mountain View
• ISP: Google LLC
• Latitude/Longitude: 37.40599, -122.078514

Cross-reference these values by visiting http://ipwho.is/8.8.8.8 in a browser. The code responsible for this parsing resides in lines 40‑78 of GhostTR.py, where the script accesses keys like country, city, and connection.isp from the response dictionary.

Testing the Self-IP Display (Option 2)

Choose option 2 to execute showIP(). This function calls https://api.ipify.org/ and requires no user input.

Compare the printed IP address against the output of:

curl https://api.ipify.org/

Both values must match exactly. This validates that the requests.get call on line 73 of GhostTR.py correctly retrieves the public-facing IP address.

Testing the Phone Number Tracker (Option 3)

Select option 3 to invoke phoneGW(). Input a valid international number in E.164 format, such as +14155552671 (a US number).

The script uses phonenumbers.parse() (line 87) to extract:

• Location and timezone
• Carrier name (e.g., AT&T Mobility)
• Number type (mobile vs. fixed-line)
• Validity flags

Confirm that the "Valid number" field reports True and that the international formatting matches standard E.164 conventions. Invalid inputs like 12345 should trigger the exception handler built into the function.

Testing the Username Tracker (Option 4)

Choose option 4 to run TrackLu(). Enter a username known to exist on multiple platforms, such as torvalds.

The function iterates through a hardcoded list of social media URLs (lines 121‑168) and issues GET requests to endpoints like https://www.github.com/torvalds. For each HTTP 200 response, it prints [ + ] PlatformName : URL; otherwise, it prints "Username not found".

Verify accuracy by manually opening one of the reported URLs in a browser to confirm the profile loads. Test with a random string (e.g., asdfqwertyuiop1234) to confirm all platforms report "Username not found".

Edge Case and Error Handling Validation

Robust testing includes verifying behavior with malformed or extreme inputs.

• Invalid IP Address: Input 999.999.999.999. The API will return an error JSON, and the script may raise a KeyError if fields are missing. Observe whether the crash occurs or if the output simply shows empty values.
• Malformed Phone Number: Input abc123 or 12345. The phonenumbers.parse() function should raise a NumberParseException; confirm the script catches this and displays an error message rather than a traceback.
• Network Failure: Disconnect your internet connection and attempt any option. The underlying requests library will raise a ConnectionError. Note that the current implementation (as of the source analysis) does not wrap these calls in try-except blocks, so expect uncaught exceptions.
• Non-existent Username: Use a high-entropy string like xyz789nonexistent. All social checks should return negative results, confirming the detection logic works for absent profiles.

These tests reveal the tool's current error-handling boundaries and identify areas where additional exception trapping could improve stability.

Key Files for Reference

File	Purpose	Testing Relevance
GhostTR.py	Main executable containing all logic	Contains IP_Track, phoneGW, TrackLu, and the interactive loop
requirements.txt	Dependency manifest	Defines requests and phonenumbers versions required for API calls
README.md	Documentation	Provides installation context and usage screenshots

Summary

• GhostTrack is a single-file Python CLI tool in GhostTR.py that performs OSINT lookups via public APIs.
• Testing is manual: install dependencies (requests, phonenumbers), run python3 GhostTR.py, and exercise each menu option.
• Validate IP Tracker (lines 40‑78) against http://ipwho.is/ responses using known IPs like 8.8.8.8.
• Validate Phone Tracker (lines 80‑108) with international format numbers to confirm phonenumbers parsing accuracy.
• Validate Username Tracker (lines 121‑168) by cross-referencing reported URLs in a browser.
• Test edge cases (invalid IPs, malformed phones, network outages) to assess current error-handling limitations.

Frequently Asked Questions

Can GhostTrack be tested without an internet connection?

No. All four core functions—IP_Track, showIP, phoneGW, and TrackLu—rely on live web requests to ipwho.is, api.ipify.org, and various social media platforms. Without connectivity, the requests library will raise ConnectionError exceptions that the current codebase does not catch.

How do I verify the IP Tracker data is accurate?

Cross-reference the terminal output with the raw API response. Visit http://ipwho.is/{ip} directly in your browser (replacing {ip} with your test address) and compare fields like country, city, and org against what GhostTR.py prints on lines 45‑78. Any discrepancy indicates a parsing error in the script's JSON handling.

Why does the Username Tracker report "Username not found" for an existing account?

Social media platforms often return HTTP 200 even for reserved or suspended usernames, or they may require specific headers to avoid bot detection. The TrackLu function (lines 121‑168) performs a simple GET request and checks the status code. If the site returns a 200 for a "not found" page (soft 404), GhostTrack will incorrectly report the user as found. Verify by manually opening the URL printed in the terminal.

Is there an automated test suite for GhostTrack?

No. According to the source code analysis, the repository contains no tests/ directory or unit test files. Validation is entirely interactive. However, you can create a custom test harness by importing functions from GhostTR.py into a separate Python script and asserting against known API responses, provided you mock the network calls or handle rate limits carefully.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}