testspec-cli/README.md

TestSpec CLI

A powerful CLI tool that converts natural language requirements into structured unit test cases for Jest, pytest, and Go testing frameworks.

Features

• Natural Language Parsing: Write test requirements in plain English like "the login function should reject invalid email formats"
• Multi-Framework Support: Generate tests for Jest, pytest, and Go testing frameworks
• Auto-Detection: Automatically detects your project's test framework
• Interactive Mode: Guided wizard for creating comprehensive test cases
• Smart Edge Cases: Intelligent suggestions for boundary conditions and edge cases
• Multiple Output Formats: Output to stdout, files, or clipboard

Installation

Prerequisites

• Node.js >= 18.0.0
• npm or yarn

Install from Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/testspec-cli.git
cd testspec-cli
npm install
npm run build
npm link

Global Install

npm install -g testspec-cli

Quick Start

Generate Tests from Natural Language

# Basic usage
testspec generate "the login function should reject invalid email formats"

# Specify framework explicitly
testspec generate "the calculateTotal function should return correct sum" --framework pytest

# Output to file
testspec generate "the validatePassword function should reject weak passwords" --output tests/validatePassword.test.ts

Interactive Mode

Launch a guided wizard to create test cases:

testspec interactive

Detect Framework

Check which test framework is detected in your project:

testspec detect

Commands

generate

Generate unit tests from natural language requirements.

testspec generate "requirement" [options]

Options:

Flag	Short	Description
--framework <framework>	-f	Test framework (jest, pytest, go)
--output <path>	-o	Output file path
--interactive	-i	Enter interactive mode
--no-edge-cases		Disable automatic edge case suggestions
--json		Output in JSON format

Examples:

# Jest (default)
testspec generate "the userService should reject invalid email"

# Pytest
testspec generate "the calculateTotal should return the correct sum" --framework pytest --output test_calc.py

# Go testing
testspec generate "the validator should reject invalid input" --framework go --output validator_test.go

interactive

Launch interactive wizard for test creation.

testspec interactive

Follow the prompts to:

1. Enter function name and description
2. Define expected behavior
3. Add test inputs
4. Choose test framework
5. Include edge cases

detect

Detect test framework in current project.

testspec detect [options]

Options:

Flag	Short	Description
--path <dir>	-p	Directory to scan
--json		Output in JSON format

Configuration

Create a .testspecrc.json file in your project root:

{
  "defaultFramework": "jest",
  "outputFormat": "stdout",
  "edgeCaseLevel": "standard",
  "autoDetect": true,
  "includeEdgeCases": true
}

Configuration Options

Option	Description	Default
defaultFramework	Framework to use when auto-detection fails	-
outputFormat	Default output format	stdout
edgeCaseLevel	Edge case suggestions level	standard
autoDetect	Enable auto-detection	true
includeEdgeCases	Include edge cases	true

Environment Variables

Variable	Description
TESTSPEC_DEFAULT_FRAMEWORK	Default framework when detection fails

Examples

Email Validation Tests

testspec generate "the validateEmail function should reject invalid email formats" --framework jest

Generated Jest test:

describe('validateEmail', () => {
  it('validateEmail should reject invalid email formats', () => {
    expect(() => validateEmail('invalid-email')).toThrow();
  });
});

Password Validation Tests

testspec generate "the validatePassword function should reject weak passwords" --framework pytest --output test_password.py

Generated pytest test:

def test_validatePassword_reject_weak_passwords():
    with pytest.raises(Exception):
        validatePassword('weak')

Go Testing

testspec generate "the Calculate function should return correct result" --framework go --output calculate_test.go

Generated Go test:

func TestCalculate(t *testing.T) {
    t.Run("should_return_correct_result", func(t *testing.T) {
        result := Calculate(input)
        if result != expected {
            t.Errorf("Expected %v, got %v", expected, result)
        }
    })
}

Supported Frameworks

Framework	Language	File Extensions	Detection
Jest	JavaScript/TypeScript	.test.ts, .spec.ts, .test.js	package.json (jest dependency)
pytest	Python	test_*.py, *_test.py	requirements.txt, setup.py
Go testing	Go	*_test.go	go.mod

Natural Language Patterns

The parser understands various patterns:

Pattern	Example
should reject	"login should reject invalid credentials"
must accept	"validator must accept valid input"
will return	"calculator will return the sum"
should throw	"parser should throw on invalid syntax"
must validate	"input must validate email format"

Edge Cases

TestSpec automatically suggests edge cases based on input types:

Type	Suggested Edge Cases
Email	Empty, missing @, invalid domain, valid format
Password	Empty, too short, missing special chars, common passwords
Number	Zero, negative, max value, decimals
String	Empty, unicode, special chars, SQL injection
Date	Past, future, invalid, timezone
URL	Missing protocol, invalid domain, query params

Development

Setup

npm install
npm run build
npm test

Commands

npm run build      # Compile TypeScript
npm run lint       # Run ESLint
npm run typecheck  # TypeScript type checking
npm test           # Run all tests
npm run test:unit  # Run unit tests
npm run test:integration  # Run integration tests

Project Structure

testspec-cli/
├── bin/
│   ├── dev.js       # Development entry point
│   └── run.js       # Production entry point
├── src/
│   ├── commands/
│   │   ├── generate.ts    # Generate command
│   │   ├── interactive.ts # Interactive wizard
│   │   └── detect.ts      # Framework detection
│   ├── lib/
│   │   ├── parser.ts          # Natural language parser
│   │   ├── frameworkDetector.ts # Framework detection
│   │   ├── testGenerator.ts   # Test code generation
│   │   ├── edgeCases.ts       # Edge case database
│   │   └── types.ts           # TypeScript types
│   ├── templates/
│   │   ├── jest.ts     # Jest template
│   │   ├── pytest.ts   # pytest template
│   │   └── go.ts       # Go template
│   └── index.ts        # Main entry
├── test/
│   ├── unit/           # Unit tests
│   └── integration/    # Integration tests
└── package.json

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License - see LICENSE file for details.