Markdown To M-Rows

MAMOW is a multi-format CLI tool for converting test cases between Markdown, Gherkin, and Excel formats. Designed for QA engineers and test automation developers, it streamlines the process of converting human-readable test specifications into structured formats with automatic tag classification.

Key Features:

• 🔄 Multi-format conversion: Gherkin ↔ Markdown ↔ Excel
• 🏷️ Automatic tag classification: 5 standardized metadata categories
• 📁 Directory processing: Batch, merge, and single file modes
• 🎨 Beautiful CLI: Colorful interface with progress indicators
• 📋 Hierarchical help: Context-aware help system

• 🚀 Getting Started - Installation & setup
• 📖 How to Use - CLI usage overview
• 🎯 Getting Help - Hierarchical help system
• 📝 Legacy Mode - Markdown → Excel conversion
• 🔄 Convert Mode - Multi-format conversion
• 📋 Examples - Practical usage examples
• 🏷️ Tag Classification - Automatic tag handling
• 🛠 Troubleshooting - Common issues & solutions

Before you begin, ensure you have the following installed on your system:

• Python 3.9+ (Check with python3 --version or python --version)
• Git (Check with git --version)
• pip (Python package installer)

Clone the project from the very beginning using the following command:

git clone https://github.com/hanifrazin/MAMOW.git
cd MAMOW

MAMOW provides two ways to run the tool:

The installation scripts below make the mamow command available globally. They handle everything — including virtual environment creation and dependency installation — automatically on the first run.

Option A — Quick Install (Recommended):

Run the installation script from the project root. This copies a launcher into /usr/local/bin:

chmod +x src/executable_scripts/install.sh
./src/executable_scripts/install.sh

Option B — Manual PATH Setup (no sudo needed):

If you don't have sudo access, add the scripts folder to your shell profile instead:

echo 'export PATH="$PATH:'"$(pwd)"'/src/executable_scripts"' >> ~/.zshrc
source ~/.zshrc

How it works: The mamow bash script resolves its real path, creates a .venv virtual environment with all dependencies on first run, then executes src/main.py with your arguments.

Run the installation batch script in Command Prompt (or PowerShell). This adds the src\executable_scripts folder to your user PATH:

.\src\executable_scripts\install.bat

After installation, restart your terminal for the PATH changes to take effect.

How it works: The mamow.bat script creates a .venv and installs dependencies on first run. It also attempts to build a standalone mamow.exe via PyInstaller for faster subsequent launches. If PyInstaller is not available, it falls back gracefully to running via Python.

💡 First-run behavior: When you run mamow for the first time (on any platform), it will automatically:

1. Create a Python virtual environment (.venv/) in the project root
2. Install all required dependencies (pydantic, openpyxl, rich)
3. Execute your command — no manual pip install needed

MAMOW is a multi-format test case converter with two main operation modes:

For converting Markdown test cases to Excel spreadsheets with advanced directory processing.

For converting between Gherkin, Markdown, and Excel formats with automatic tag classification.

MAMOW features a hierarchical help system to make it easy to find the right information:

# Show main overview with all commands
mamow

# Show help for Markdown → Excel conversion
mamow --help

# Show help for format conversion (Gherkin ↔ Markdown ↔ Excel)
mamow convert --help

Convert Markdown test cases to Excel spreadsheets with directory processing capabilities.

Basic Usage:

mamow -i <input_path> [-o <output_path>] [-c <config_path>] [--merge | --single]

Using Python directly:

python src/main.py -i <input_path> [-o <output_path>] [-c <config_path>] [--merge | --single]

Convert between Gherkin, Markdown, and Excel formats with automatic tag classification.

Basic Usage:

mamow convert -i <input_file> -f <format> [-o <output_file>]

Format Options:

• md - Markdown file (.md)
• gherkin - Gherkin/Feature file (.feature)
• feature - Alias for gherkin
• excel - Excel spreadsheet (.xlsx)

When converting between Gherkin and Markdown, MAMOW automatically classifies tags into 5 standardized metadata blocks:

1. Priority - Uppercase, comma-separated (e.g., P1, P2)
2. TC Type - Capitalized (e.g., Positive, Negative)
3. Test Type - Lowercase (e.g., smoke, regression)
4. Platform Type - Uppercase, comma-separated (e.g., UI, MOBILE)
5. Other Tags - Lowercase, comma-separated (e.g., login, bug-123)

When the input is a directory in Legacy Mode, MAMOW supports three modes:

Note: --merge and --single cannot be used together. If the input is a single file, both flags are ignored.

When the output path is a directory, MAMOW auto-generates filenames as follows:

When the input is a directory, MAMOW automatically creates a result_<input_folder_name> subfolder inside the output directory to keep your exports organized. For example:

mamow -i samples/data/ -o samples/output/ --merge

→ Exports to samples/output/result_data/data_merge.xlsx

This prevents output clutter and keeps results from different input directories separated.

1. Process a single Markdown file:

mamow -i samples/data/login.md -o samples/output/login.xlsx

2. Batch process all files in a directory (default mode):

mamow -i samples/data/ -o samples/output/

→ Each .md file becomes its own .xlsx inside samples/output/result_data/

3. Merge all files in a directory into a single Excel workbook:

mamow -i samples/data/ -o samples/output/data.xlsx --merge

→ All test cases combined into samples/output/result_data/data_merge.xlsx

4. Export each file separately using --single mode:

mamow -i samples/data/ -o samples/output/ --single

→ Each .md → separate .xlsx (e.g., login_single.xlsx, login-2_single.xlsx) inside samples/output/result_data/

5. Run using fallback default paths (as defined in config.json):

mamow -i login.md

→ Looks for samples/input/login.md and outputs to samples/output/

1. Markdown → Gherkin with tag classification:

mamow convert -i test.md -f gherkin -o test.feature

→ Converts Markdown to Gherkin with tags automatically classified

2. Gherkin → Markdown:

mamow convert -i test.feature -f md -o test.md

→ Converts Gherkin to Markdown with proper tag formatting

3. Markdown → Excel (via convert mode):

mamow convert -i test.md -f excel -o test.xlsx

4. Gherkin → Excel:

mamow convert -i test.feature -f excel -o test.xlsx

5. Auto-generated output naming:

mamow convert -i input.feature -f md

→ Creates input.md in the same directory

MAMOW features a beautiful, colorful CLI interface:

╭──────────────────────────────────────────────────────╮
│                                                      │
│        __  __    _    __  __  _____        __        │
│       |  \/  |  / \  |  \/  |/ _ \ \      / /        │
│       | |\/| | / _ \ | |\/| | | | \ \ /\ / /         │
│       | |  | |/ ___ \| |  | | |_| |\ V  V /          │
│       |_|  |_/_/   \_\_|  |_|\___/  \_/\_/           │
│                                                      │
│                Markdown To M-Rows                    │
│                                                      │
╰──────────────────────────────────────────────────────╯

The interface provides:

• Colorful output with clear visual hierarchy
• Progress bars for long operations
• Well-formatted tables and panels
• Intuitive help system with examples

MAMOW automatically classifies Gherkin tags into 5 standardized metadata blocks when converting to/from Markdown:

Example Gherkin tags:

@P1 @Negative @UI @smoke @login @bug-123

Becomes in Markdown:

**Priority**: P1
**TC Type**: Negative
**Test Type**: smoke
**Platform Type**: UI
**Other Tags**: login, bug-123

• Feature files: .feature extension
• Scenario tags: Tags before each scenario
• Feature tags: Tags at the feature level
• Roundtrip preservation: All tags preserved through conversions

@P1 @smoke @UI
Feature: Login Module
  As a user I want to login to the system
  
  @Negative @MOBILE
  Scenario: Invalid login on mobile
    Given I am on mobile login page
    When I enter wrong credentials
    Then error message is displayed

Here are some common issues you might encounter and how to fix them:

• Solution: Ensure Python is added to your system's PATH during installation. On Windows, you might need to use python instead of python3.

• Solution (macOS/Linux): Ensure you created the venv with the exact name venv. Check your current directory is the project root.
• Solution (Windows): If you receive a script execution policy error in PowerShell, run Set-ExecutionPolicy Unrestricted -Scope CurrentUser as an Administrator, or use Command Prompt to run venv\Scripts\activate.bat.

• Solution: This means the dependencies are not installed or your virtual environment is not active. Make sure you activate the virtual environment (source venv/bin/activate) and run pip install -r requirements.txt again.

• Solution: Verify the path to your Markdown file is correct relative to your current terminal working directory. You can also provide an absolute path to the file.

If you try to run mamow and get an error, ensure you have run the installation script first (install.sh for Mac/Linux, install.bat for Windows). If issues persist, follow these manual fixes:

🍎 macOS & 🐧 Linux:

• Issue A: Permission Denied The scripts need execution permissions. Fix: Run the following command from the project root:

  chmod +x src/executable_scripts/mamow
  chmod +x src/executable_scripts/install.sh

• Issue B: Command not found (mamow: command not found) The install.sh might have failed to write to /usr/local/bin due to permission issues or restricted environments. Fix 1 (Manual Symlink):

  sudo ln -s "$(pwd)/src/executable_scripts/mamow" /usr/local/bin/mamow

  Fix 2 (Add to PATH): Add the folder to your ~/.zshrc or ~/.bashrc.

  echo 'export PATH="$PATH:'"$(pwd)"'/src/executable_scripts"' >> ~/.zshrc
  source ~/.zshrc

🪟 Windows:

If you ran install.bat but mamow still isn't recognized in PowerShell or Command Prompt:

• Issue: PATH environment variable didn't refresh Fix: Restart your PowerShell or Command Prompt window. The PATH changes applied by install.bat take effect in new terminal sessions.

• Issue: Script Execution Disabled (PowerShell) Fix: Open PowerShell as Administrator and run:

  Set-ExecutionPolicy Unrestricted -Scope CurrentUser

• Alternative for Git Bash Users: If you prefer Git Bash instead of PowerShell, Git Bash reads the bash mamow file instead of mamow.bat. You can alias it by running:

  echo "alias mamow='bash $(pwd)/src/executable_scripts/mamow'" >> ~/.bash_profile
  source ~/.bash_profile