KVS TestSmith 🛠️

Automatic Flutter test generation powered by static analysis.

A powerful, production-ready CLI tool that automatically generates Flutter unit tests, widget tests, and integration tests by deeply analyzing your Dart source code using the Dart Analyzer AST, and fully implementing working tests with local AI powered by DeepSeek Coder via Ollama.

Think of it as Rails generators, but for Flutter tests.

---

✨ Features

• 🔍 Project Scanner: Recursively scans lib/ while intelligently ignoring generated files (.g.dart, .freezed.dart, .config.dart) and build directories.
• 🌳 AST Parsing: Uses package:analyzer to accurately detect StatelessWidget, StatefulWidget, Services, Repositories, Controllers, BLoCs, and Cubits.
• 📁 Folder Mirroring: Tests are generated in a structure that perfectly mirrors your lib/ directory inside your test/ directory.
• 🧪 Smart Widget Tests: Automatically generates testWidgets() with pumpWidget() and a MaterialApp wrapper.
• 🔬 Smart Unit Tests: Generates group() + test() stubs implementing the AAA pattern (Arrange, Act, Assert) for every public method.
• 🤖 AI Test Implementation (Local): Automatically implement full working test files (bypassing stubs) using local Ollama (deepseek-coder) with intelligent UI Element extraction from your AST.
• 🎭 Mock Generation: Automatically generates mocktail mock classes inline for your services.
• 👀 Watch Mode: Watches lib/ and auto-generates tests live as you create or modify files.
• 📊 Coverage Support: Run flutter test --coverage and get a parsed terminal summary of lines covered.

---

📦 Installation

Global Usage (Recommended for Users)

To use the CLI globally from anywhere on your machine, activate it via Pub:

dart pub global activate kvs_testsmith

Local/Development Usage (Recommended for Developers)

If you are working directly in this repository, you can activate it from source to use the kvs_testsmith command globally:

1. Activate from Source:

   dart pub global activate --source path .
   

2. Using the convenience script:

   ./kvs_testsmith generate
   

3. Directly via Dart:

   dart run kvs_testsmith:kvs_testsmith generate
   

---

🚀 Usage

Run the tool from the root of your Flutter project. If you have it activated globally, you can just use kvs_testsmith. Otherwise, use ./kvs_testsmith (if in the repo) or dart run kvs_testsmith:kvs_testsmith.

Generate all missing tests

kvs_testsmith generate

Advanced Generation Options

# Generate only widget tests
kvs_testsmith generate --widgets

# Generate only unit tests
kvs_testsmith generate --unit

# Generate only for files that don't already have tests
kvs_testsmith generate --only-missing

# Combine flags
kvs_testsmith generate --unit --only-missing

Watch Mode

Leave this running in a terminal. As you add or modify Dart files in your lib/ directory, TestSmith will automatically generate tests for them.

kvs_testsmith watch

🤖 AI Test Implementation (DeepSeek Coder + Ollama)

KVS TestSmith can leverage a local AI to fully implement your interaction test files instead of just generating structural AAA stubs. The orchestrator will parse your AST, detect interactive UI elements (like ElevatedButton, TextField, GestureDetector) and pipe them to the local LLM.

Ollama Setup Instructions

1. Download and install Ollama on your machine.
2. Open your terminal and securely pull the underlying coding model by running:

   ollama run deepseek-coder
   

3. Once Ollama is active locally, you can utilize the TestSmith AI feature:

kvs_testsmith generate --ai

Coverage Report

Runs your test suite with coverage enabled and prints a clean summary to the terminal.

kvs_testsmith coverage

---

🏗️ How It Works (Examples)

KVS TestSmith reads your code structure and generates tailored tests.

1. Widget Code → Widget Test

If you have a widget at lib/features/auth/ui/login_page.dart:

// Generated by TestSmith at test/features/auth/ui/login_page_test.dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:my_app/features/auth/ui/login_page.dart';

void main() {
  group('LoginPage', () {
    testWidgets('renders correctly', (tester) async {
      await tester.pumpWidget(
        const MaterialApp(
          home: const LoginPage(),
        ),
      );

      expect(find.byType(LoginPage), findsOneWidget);
    });
  });
}

2. Service/Repository Code → Unit Test

If you have a repository at lib/features/auth/data/auth_repository.dart with a login() method:

// Generated by TestSmith at test/features/auth/data/auth_repository_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:my_app/features/auth/data/auth_repository.dart';

class MockAuthRepository extends Mock implements AuthRepository {}

void main() {
  group('AuthRepository', () {
    late AuthRepository sut; // System Under Test

    setUp(() {
      sut = AuthRepository();
    });

    test('should be instantiated', () {
      expect(sut, isNotNull);
    });

    // TestSmith detected your 'login' method!
    test('login works correctly', () {
      // TODO: Arrange

      // TODO: Act
      // final result = sut.login();

      // TODO: Assert
      // expect(result, expectedValue);
    });
  });
}

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to set up the project and submit pull requests.

If you find a bug or have a feature request, please open an issue.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🛠 Troubleshooting

zsh: command not found: kvs_testsmith

If you get this error after running dart pub global activate, your system doesn't know where the Dart binaries are located.

Fix for macOS/Linux: Add the following line to your ~/.zshrc or ~/.bash_profile:

export PATH="$PATH":"$HOME/.pub-cache/bin"

Then restart your terminal or run source ~/.zshrc.

Fix for Windows: Add %USERPROFILE%\AppData\Local\Pub\Cache\bin to your system Environment Variables (PATH).

---

Built with ❤️ for the Flutter community by the KVS TestSmith Maintainers.