ft-ps-tester 1.0.4

A Python tester for the 42 push_swap project with controlled disorder generation and performance grading.

ft_ps_tester

A Python-based tester for the 42 push_swap project. It generates controlled random sequences with specific disorder levels, runs your push_swap executable, validates the output, and grades performance against 42 thresholds.

---

---

Features

• Controlled disorder generation — creates sequences with precise inversion percentages.
• Four test modes — simple, medium, complex, and adaptive.
• Output validation — simulates operations to verify sorting correctness.
• Performance grading — compares operation counts against 42 thresholds (excellent / good / pass / fail).
• Failure report — concise summary of timeouts, invalid operations, and limit exceedances.

---

Requirements

• Python 3
• A compiled push_swap executable that accepts arguments and prints operations to stdout

---

Installation

Tip: If you run into installation errors, try updating pip first:

pip install --upgrade pip
# or
pip3 install --upgrade pip

Option 1: Install from PyPI (recommended)

Using pip:

pip install ft_ps_tester

Using pip3:

pip3 install ft_ps_tester

User-local install (no sudo required — pip):

pip install --user ft_ps_tester

User-local install (no sudo required — pip3):

pip3 install --user ft_ps_tester

Using python3 -m pip:

python3 -m pip install ft_ps_tester

Note: When using --user, the ft_ps_tester binary is installed to a user-local bin/ directory (e.g. ~/.local/bin on Linux/macOS, or %APPDATA%\Python\Python3x\Scripts on Windows). Make sure this directory is on your PATH, or use the python3 -m execution methods shown below.

---

Option 2: Install from source

Clone this repository:

git clone https://github.com/italoalmeida0/ft_ps_tester.git
cd ft_ps_tester

Editable / development mode (pip):

pip install -e .

Editable / development mode (pip3):

pip3 install -e .

Editable / development mode (python3 -m pip):

python3 -m pip install -e .

Normal install (pip):

pip install .

Normal install (pip3):

pip3 install .

Normal install (python3 -m pip):

python3 -m pip install .

User-local install from source (pip --user):

pip install --user -e .

User-local install from source (pip3 --user):

pip3 install --user -e .

---

Option 3: Run with pipx (isolated, no install required)

If you have pipx installed, you can run the tester directly without permanently installing it:

pipx run ft_ps_tester ./push_swap

Single test run:

pipx run ft_ps_tester ./push_swap 500 complex

Or install it into an isolated environment:

pipx install ft_ps_tester

Then run normally:

ft_ps_tester ./push_swap

---

Make sure your push_swap binary is compiled and executable:

make
chmod +x push_swap

---

Usage

Full test suite (recommended)

Tests 100 and 500 elements across all four modes (100 tests each).

If the ft_ps_tester command is on your PATH:

ft_ps_tester ./push_swap

If the command is not found (common with --user installs), run via the module:

python3 -m ft_ps_tester ./push_swap

Or using the .cli submodule directly:

python3 -m ft_ps_tester.cli ./push_swap

Or using python directly:

python -m ft_ps_tester ./push_swap

From the cloned source directory (no install required):

python3 ft_ps_tester/cli.py ./push_swap

---

Single test run

Test a specific size and mode:

ft_ps_tester ./push_swap <size> <mode>

If ft_ps_tester is not on your PATH:

python3 -m ft_ps_tester ./push_swap <size> <mode>

Or via the .cli submodule:

python3 -m ft_ps_tester.cli ./push_swap <size> <mode>

Example:

ft_ps_tester ./push_swap 500 complex

Or:

python3 -m ft_ps_tester ./push_swap 500 complex

---

Failure reports (--reports)

Enable automatic report generation when a test fails (invalid sort, operation limit exceeded, or timeout). Reports are saved in the same directory as the push_swap executable.

Two files are generated per failure:

File suffix	Content
_ops_N.txt	Raw output (operations) from push_swap
_nums_N.txt	Input numbers passed to push_swap

The numbering (_1, _2, …) is shared between both files: if either an _ops_N or _nums_N file already exists, the next number is used so both files always share the same suffix.

Example:

ft_ps_tester --reports ./push_swap

If a failure occurs in the 100_simple test, the following files are created next to ./push_swap:

report_100_simple_ops_1.txt
report_100_simple_nums_1.txt

If another failure occurs later (or if one of those files already existed), the next pair becomes:

report_100_simple_ops_2.txt
report_100_simple_nums_2.txt

You can also use --reports with single test runs:

ft_ps_tester --reports ./push_swap 500 complex

---

Modes / Flags

Your push_swap must support the following flags (passed as --<mode> before the numbers):

Mode	Disorder range	Description
simple	15.0% – 19.9%	Nearly sorted sequences
medium	20.0% – 49.9%	Moderately shuffled sequences
complex	50.0% – 55.0%	Heavily shuffled sequences
adaptive	15.0% – 55.0%	Random disorder across the full spectrum

Note: If your push_swap does not implement these flags, the tester will still work if your program ignores unknown flags and simply sorts the provided numbers. However, for accurate mode-based testing, your push_swap should parse and use the flag to adjust its algorithm.

---

Grading Thresholds

Size	Excellent	Good	Pass
100	< 700	< 1500	≤ 2000
500	< 5500	< 8000	≤ 12000

Results are shown with color-coded grades:

• EXCELLENT — green
• GOOD — blue
• PASS — yellow
• FAIL — red

---

Example Output

Running FULL TEST SUITE for ./push_swap

>> Testing Size: 100 | Mode: SIMPLE  ..................................................
>> Testing Size: 100 | Mode: MEDIUM  ..................................................
>> Testing Size: 100 | Mode: COMPLEX ..................................................
>> Testing Size: 100 | Mode: ADAPTIVE..................................................
>> Testing Size: 500 | Mode: SIMPLE  ..................................................
>> Testing Size: 500 | Mode: MEDIUM  ..................................................
>> Testing Size: 500 | Mode: COMPLEX ..................................................
>> Testing Size: 500 | Mode: ADAPTIVE..................................................

========================================================================================
PERFORMANCE SUMMARY
========================================================================================
SIZE   | MODE     | MAX (GRADE)        | MIN (GRADE)        | AVG (GRADE)        | FAILS
----------------------------------------------------------------------------------------
100    | SIMPLE   | 450 (EXCELLENT)    | 320 (EXCELLENT)    | 380 (EXCELLENT)    | 0
100    | MEDIUM   | 1200 (GOOD)        | 900 (EXCELLENT)    | 1050 (GOOD)        | 0
...

---

License

This project is licensed under the MIT License.