taskmaprcli

v1.2.0

Published

7 months ago

CLI tool to analyze UI flows in React applications and generate complete E2E tests with AI

0High
0Medium
0Low

james2723827839

ui-flows react analysis navigation testing e2e playwright cypress ai test-generation automation nextjs flow-analysis

TaskMapr CLI

Analyze UI flows and navigation patterns in your React applications

TaskMapr CLI automatically discovers routes, navigation patterns, and user flows in your React/JavaScript applications by analyzing your codebase structure.

Features

🗺️ Automatic Flow Discovery - Detects all routes and navigation paths
🧪 E2E Test Generation - Auto-generate Playwright/Cypress tests from flows
✨ AI Test Generation (NEW!) - Generate complete, production-ready tests with AI - no TODOs!
🔍 Repository Indexing - Vector search for semantic code queries
📊 Detailed Reports - JSON and Markdown output formats
🚀 Easy to Use - Run directly in any Git repository
⚡ Fast Analysis - Cloud-powered processing

Installation

Global Installation (Recommended)

npm install -g taskmaprcli

Using npx (No Installation)

npx taskmaprcli analyze

Usage

Analyze UI Flows

Run this command in your React project directory:

taskmaprcli analyze

This will:

Detect your GitHub repository
Analyze all React/JS files
Extract routes, navigations, and interactions
Generate detailed reports

Options

taskmaprcli analyze [options]

Options:
  -o, --output <path>     Output directory (default: ./taskmaprcli-output)
  -b, --backend <url>     Backend URL (default: https://chartmate-backend.onrender.com)
  --branch <name>         Git branch to analyze (default: main)
  -t, --timeout <seconds> Request timeout in seconds (default: 900)
  --verbose               Show detailed progress updates
  -h, --help              Display help

Examples

# Analyze with custom output directory
taskmaprcli analyze --output ./flow-reports

# Analyze specific branch
taskmaprcli analyze --branch develop

# Increase timeout for large repositories (30 minutes)
taskmaprcli analyze --timeout 1800

# Show detailed progress with verbose mode
taskmaprcli analyze --verbose

# Combine multiple options
taskmaprcli analyze --timeout 1800 --verbose --output ./reports

Index Repository

Enable advanced semantic search and queries:

taskmaprcli index

This creates a vector index of your codebase for:

Natural language code search
AI-powered code insights
Semantic similarity queries

Options

taskmaprcli index [options]

Options:
  -b, --backend <url>   Backend URL (default: https://chartmate-backend.onrender.com)
  --branch <name>       Git branch to index (default: main)
  --update              Force update if already indexed
  -h, --help           Display help

Generate E2E Tests

Automatically generate end-to-end tests from your flow analysis:

taskmaprcli generate-tests

This creates ready-to-use test suites for Playwright or Cypress based on your discovered routes, navigations, and user interactions.

Generate AI-Enhanced Tests ✨ NEW!

v1.1.0 introduces AI-powered test generation that creates complete, runnable tests with no manual coding required:

taskmaprcli generate-ai-tests

Unlike template generation, AI-enhanced tests include:

✅ Complete implementations - NO TODOs or placeholders
✅ Smart selectors - Multiple fallback strategies (data-testid, aria-labels, text content)
✅ Full authentication flows - Complete login/logout implementations
✅ Comprehensive assertions - Page state validation, element visibility checks
✅ Test fixtures - Mock data generators and test utilities
✅ Error handling - Timeouts, retries, graceful failures

🔍 Repository Indexing (v1.2.0+)

Important: For best results, index your repository first!

The CLI will automatically check if your repository is indexed before generating tests:

# 1. Index your repository (RECOMMENDED!)
taskmaprcli index-repo owner/repo

# 2. Then generate AI tests
taskmaprcli generate-ai-tests

Why indexing matters:

✅ 85%+ test pass rate vs 50% without indexing
✅ Real selectors - Finds actual data-testid, buttons, links from your code
✅ Accurate tests - Uses patterns from YOUR components, not generic guesses
✅ Less manual work - Tests work immediately, no debugging required

What happens without indexing:

🔍 Checking if owner/repo is indexed...
❌ Repository has not been indexed yet!

Indexing allows the AI to:
  • Find actual UI elements (buttons, links, data-testid)
  • Generate accurate selectors from your code
  • Create tests that actually work

? Generate basic tests without indexing? (y/N)

You can still proceed without indexing, but tests will use URL navigation only with generic patterns.

Options

taskmaprcli generate-tests [options]

Options:
  -i, --input <path>       Path to flows.json file (default: ./taskmaprcli-output/flows.json)
  -o, --output <path>      Output directory for tests (default: ./tests)
  -f, --framework <name>   Test framework: playwright or cypress (default: playwright)
  -u, --base-url <url>     Base URL for tests (default: http://localhost:3000)
  --no-auth                Exclude authentication helpers
  --no-config              Skip generating config file
  -h, --help              Display help

AI Test Generation Options

taskmaprcli generate-ai-tests [options]

Options:
  -i, --input <path>       Path to flows.json file (default: ./taskmaprcli-output/flows.json)
  -o, --output <path>      Output directory for tests (default: ./)
  -f, --framework <name>   Test framework: playwright or cypress (default: playwright)
  -u, --base-url <url>     Base URL for tests (default: http://localhost:3000)
  -b, --backend <url>      Backend URL (default: https://chartmate-backend.onrender.com)
  --no-auth                Exclude authentication helpers
  -c, --context <text>     App context for better test generation
  -h, --help              Display help

AI Test Generation Examples

# Basic AI test generation
taskmaprcli generate-ai-tests

# With application context (highly recommended!)
taskmaprcli generate-ai-tests \
  --context "E-commerce site with product listings, shopping cart, and Stripe checkout"

# Generate Cypress tests with context
taskmaprcli generate-ai-tests \
  --framework cypress \
  --context "SaaS dashboard with user management, analytics, and billing"

# Custom base URL for staging
taskmaprcli generate-ai-tests \
  --base-url https://staging.app.com \
  --context "Next.js blog with user authentication and admin panel"

Template Test Generation Examples

# Generate Playwright tests (default)
taskmaprcli generate-tests

# Generate Cypress tests
taskmaprcli generate-tests --framework cypress

# Custom paths and base URL
taskmaprcli generate-tests \
  --input ./my-analysis/flows.json \
  --output ./e2e-tests \
  --base-url https://staging.app.com

# Skip config file (if you already have one)
taskmaprcli generate-tests --no-config

What Gets Generated

Route Tests - Tests for all discovered pages (public & protected)
Navigation Flow Tests - Tests for user navigation patterns
Interaction Tests - Tests for button clicks, form submissions, etc.
Auth Helpers - Pre-configured authentication scaffolding
Configuration Files - Complete test framework setup
Setup Documentation - README with installation and usage instructions

Complete Workflow (AI-Enhanced)

# 1. Analyze your app
taskmaprcli analyze

# 2. Generate AI-enhanced tests (complete, no TODOs!)
taskmaprcli generate-ai-tests \
  --context "Brief description of your app"

# 3. Install test framework
npm install -D @playwright/test

# 4. Set up test credentials
echo "[email protected]" > .env.test
echo "TEST_USER_PASSWORD=TestPassword123" >> .env.test

# 5. Run tests (they're ready!)
npx playwright test

Complete Workflow (Template)

# 1. Analyze your app
taskmaprcli analyze

# 2. Generate test templates
taskmaprcli generate-tests --framework playwright

# 3. Install test framework
npm install -D @playwright/test

# 4. Customize tests (add selectors, implement auth)

# 5. Run tests
npx playwright test

Output

The CLI generates several output files:

`REPORT.md`

Human-readable Markdown report with:

Summary statistics
Discovered routes
Navigation paths
Next steps

`flows.json`

Complete flow analysis data including:

All components analyzed
Routes discovered
Navigation patterns
Interaction events

`flow-graph.json`

Graph structure with nodes and edges:

{
  "nodes": [
    {
      "id": "/dashboard",
      "type": "route",
      "label": "Dashboard",
      "requires_auth": true
    }
  ],
  "edges": [
    {
      "source": "LoginButton",
      "target": "/dashboard",
      "trigger": "onClick"
    }
  ]
}

`summary.json`

Quick overview with statistics

Requirements

Node.js 14+
Git repository with GitHub remote
Public or accessible GitHub repository

How It Works

Repository Detection - Automatically detects your GitHub repo from git config
Code Analysis - Analyzes React/JS files for navigation patterns
Flow Extraction - Identifies routes, links, and navigation triggers
Report Generation - Creates comprehensive reports in multiple formats

Use Cases

📋 Documentation - Auto-generate navigation documentation
🧪 Testing - Generate E2E tests automatically from discovered flows
🔍 Code Review - Understand application flow structure
🎯 Onboarding - Help new developers understand navigation
🏗️ Architecture - Visualize application structure
⚡ CI/CD - Integrate flow-based tests into your pipeline

Examples

Basic Analysis

cd my-react-app
taskmaprcli analyze

Output:

╭───────────────────────────────────────╮
│  🗺️  TaskMapr CLI v1.0.0      │
│  UI Flow Analyzer               │
╰───────────────────────────────────────╯

✓ Connected to backend: https://chartmate-backend.onrender.com
✓ Found: myusername/my-react-app
✓ Analyze UI flows for myusername/my-react-app? … yes

✓ Analyzed 47 components in 2m 34s

📝 Writing analysis results...

✅ Flow analysis complete!

📊 Summary:
  Components analyzed: 47
  Routes discovered: 12
  Navigations found: 34
  Flow nodes: 12
  Flow edges: 34

📁 Output files:
  ./taskmaprcli-output/REPORT.md
  ./taskmaprcli-output/flows.json
  ./taskmaprcli-output/flow-graph.json
  ./taskmaprcli-output/summary.json

🚀 Next steps:
  1. Review the report: cat ./taskmaprcli-output/REPORT.md
  2. Visualize flows using TaskMapr dashboard
  3. Index repo for advanced queries: taskmaprcli index

Index for Queries

taskmaprcli index

Output:

╭───────────────────────────────────────╮
│  🗺️  TaskMapr CLI v1.0.0      │
│  Repository Indexer            │
╰───────────────────────────────────────╯

✓ Connected to backend: https://chartmate-backend.onrender.com
✓ Found: myusername/my-react-app
✓ Index repository myusername/my-react-app? … yes

✓ Repository indexed successfully in 4m 12s

⏱️  Total time: 4m 12s

✅ Indexing complete!

📊 Summary:
  Documents processed: 81
  Branch: main
  Status: created

🚀 What you can do now:
  - Query your codebase using natural language
  - Perform semantic code search
  - Get AI-powered code insights

Local Testing

To test the CLI locally with your own backend:

1. Start Local Backend

cd /path/to/TaskMapr
python -m uvicorn src.main:app --reload --port 8000

2. Use CLI with Local Backend

# Navigate to a test repository
cd /path/to/test-repo

# Run with local backend
node /Users/jamesunsworth/CascadeProjects/TaskMapr/cli/bin/cli.js analyze --backend http://localhost:8000

# Or for indexing
node /Users/jamesunsworth/CascadeProjects/TaskMapr/cli/bin/cli.js index --backend http://localhost:8000

3. Test with Verbose Output

node /path/to/cli.js analyze --backend http://localhost:8000 --verbose --timeout 1800

Troubleshooting

"Not a git repository"

Make sure you're running the command inside a Git repository.

"Could not detect GitHub repository"

Ensure your repository has a GitHub remote:

git remote -v

"Backend is not accessible"

Check your internet connection and the backend URL. For local testing, ensure your backend is running:

curl http://localhost:8000/healthz

"Request timeout"

For large repositories, increase the timeout:

taskmaprcli analyze --timeout 1800  # 30 minutes

You can also check backend logs for processing issues.

Configuration

Create a .taskmaprcli.config.js file in your project root:

module.exports = {
  backend: 'https://chartmate-backend.onrender.com',
  output: './flow-analysis',
  branch: 'main'
};

Support

🐛 Report issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: [email protected]

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

TaskMapr CLI

Features

Installation

Global Installation (Recommended)

Using npx (No Installation)

Usage

Analyze UI Flows

Options

Examples

Index Repository

Options

Generate E2E Tests

Generate AI-Enhanced Tests ✨ NEW!

🔍 Repository Indexing (v1.2.0+)

Options

AI Test Generation Options

AI Test Generation Examples

Template Test Generation Examples

What Gets Generated

Complete Workflow (AI-Enhanced)

Complete Workflow (Template)

Output

REPORT.md

flows.json

flow-graph.json

summary.json

Requirements

How It Works

Use Cases

Examples

Basic Analysis

Index for Queries

Local Testing

1. Start Local Backend

2. Use CLI with Local Backend

3. Test with Verbose Output

Troubleshooting

"Not a git repository"

"Could not detect GitHub repository"

"Backend is not accessible"

"Request timeout"

Configuration

Support

License

Links

`REPORT.md`

`flows.json`

`flow-graph.json`

`summary.json`