ftoc - Feature Table of Contents Utility

FTOC solves the challenge of managing large Cucumber test suites by automatically analyzing feature files to improve discoverability, ensure tag consistency, and maintain quality. It generates structured documentation, comprehensive tag analysis with visualizations, and quality metrics that help teams effectively organize their BDD tests. With cross-language support and CI/CD integration, FTOC bridges the gap between test authoring and maintainable, discoverable test documentation.

Overview

ftoc analyzes Cucumber feature files to create documentation and perform quality checks, helping development teams maintain consistent BDD practices. It works with all Cucumber-compatible implementations (Java, JavaScript, Ruby, Karate) and provides sophisticated analytics to understand your test suite organization.

Key Features

• Table of Contents Generation: Creates structured TOC of all scenarios and scenario outlines
• Advanced Tag Analytics:
  • Tag occurrence metrics and co-occurrence analysis
  • Trend detection for rising and declining tag usage
  • Statistical significance indicators
  • D3.js visualizations of tag relationships
• Quality Assurance: Flags missing tags or use of low-value generic tags
• Cross-Language Support: Works with feature files in any Cucumber implementation, including Karate
• Karate Support: Specialized analysis of Karate API test files
• CI/CD Integration: Generates JUnit XML reports for integration with CI systems
• Test Pyramid Integration: System testing with Karate for robust CLI validation
• Multi-Format Output: Plain text, Markdown, HTML, and JSON reporting
• GitHub Copilot Integration:
  • IDE configurations for VS Code and JetBrains
  • CLI integration with custom aliases and scripts
  • VS Code extension prototype for enhanced feature file editing
  • Custom edit modes for common FTOC tasks

Who Is This For?

• QA Engineers working with BDD/Cucumber frameworks
• Development teams practicing Behavior-Driven Development
• DevOps engineers integrating test reporting into CI/CD pipelines
• Project managers tracking test coverage and organization

Installation

git clone https://github.com/heymumford/ftoc.git
cd ftoc
mvn clean package

Usage

java -jar target/ftoc-<version>-jar-with-dependencies.jar [OPTIONS]

Options

• -d <directory>: Specify the directory to analyze (default: current directory)
• --version, -v: Display version information
• --help: Display help message

Example

# Analyze all feature files in a specific directory
java -jar target/ftoc-0.5.1-jar-with-dependencies.jar -d src/test/resources/features

# Get version information
java -jar target/ftoc-0.5.1-jar-with-dependencies.jar --version

Programmatic Usage

Legacy API

import com.heymumford.ftoc.FtocUtility;

FtocUtility ftoc = new FtocUtility();
ftoc.initialize();
ftoc.processDirectory("/path/to/feature/files");

New Architecture (Recommended)

import com.heymumford.ftoc.FtocUtilityRefactored;
import com.heymumford.ftoc.core.impl.DefaultFeatureRepository;
import com.heymumford.ftoc.core.impl.DefaultFeatureProcessor;
import com.heymumford.ftoc.core.impl.DefaultReporter;

// Using default implementation
FtocUtilityRefactored ftoc = new FtocUtilityRefactored();
ftoc.initialize();
ftoc.processDirectory("/path/to/feature/files");

// Or with custom components
FeatureRepository repository = new DefaultFeatureRepository();
FeatureProcessor processor = new DefaultFeatureProcessor(repository);
Reporter reporter = new DefaultReporter();

FtocUtilityRefactored ftoc = new FtocUtilityRefactored(repository, processor, reporter);
ftoc.initialize();
ftoc.processDirectory("/path/to/feature/files");

Why ftoc?

Managing large suites of Cucumber tests presents challenges:

• Discoverability: Finding relevant scenarios becomes difficult as test suites grow
• Tag Consistency: Ensuring proper tagging for test selection and reporting
• Documentation: Generating up-to-date documentation from feature files
• Quality Control: Avoiding generic, unhelpful tagging patterns

ftoc addresses these challenges with automated analysis and reporting tools.

Documentation

User Documentation

• Usage Guide
• Tag Best Practices
• Tag Concordance Report
• JUnit Report Integration
• Docker Usage
• Cross-Platform Usage
• Karate Syntax Guide

Developer Documentation

• Architecture Documentation
• Architecture Decision Records (ADRs)
• C4 Architecture Diagrams
• Project Kanban Board
• GitHub Copilot Integration
• Version Management Guide
• Classpath Optimization Report
• XML Standards and Cleanup
• Security Practices
• Code Coverage
• Claude AI Assistant Guide
• Karate Testing Guide
• Test Pyramid Strategy
• Conventional Commits Guide
• Release Process
• Changelog Usage
• Performance Optimization
• TOC Formatting Guide

For all documentation, see the docs directory.

Version Management

FTOC uses semantic versioning (MAJOR.MINOR.PATCH) combined with build numbers for precise tracking:

# Display version information
./version summary

Project Structure

ftoc/
├── config/            # Configuration files and scripts
├── docs/              # Documentation
│   ├── adr/           # Architecture Decision Records
│   ├── c4/            # Architecture diagrams
│   ├── developer/     # Developer documentation
│   └── user/          # User documentation
├── src/               # Source code
│   ├── main/          # Application code
│   └── test/          # Test code
├── .github/           # GitHub templates and workflows
├── Makefile           # Build and development convenience commands
├── ftoc               # Main executable script
├── version            # Version management script
├── LICENSE            # MIT License
└── README.md          # This file

License

MIT © heymumford