README.md

✅ Spec

A streamlined testing framework for Dart & Flutter.

What is it?

Spec builds on-top of existing Dart & Flutter testing tools to provide a streamlined & elegant testing environment. Spec provides both a CLI tool and Dart package.

• Documentation

CLI

The Spec CLI allows you to run the spec command from your CLI environment and run your tests:

• Intuitive testing output interface, inspired by Jest.
• Interactive CLI (via spec --watch); automatically re-run tests when source code changes & rerunning of only failed tests.
• Run both Dart & Flutter tests in parallel with a single command.
• Run tests from multiple packages at the same time using Melos.

Package

The spec package provides a different take on how to write tests. Designed with type-safety and IDE autocompletion in mind, spec alters the way you write your tests to be more declarative, less error prone and force good habits.

Getting Started

Matchers

Spec CLI works alongside normal Dart test matchers, however also ships with custom matchers, see the API reference docs.

Example of testing using Spec matchers:

import 'package:spec/spec.dart';

void main() {
  test('future example', () async {
    final future = Future.value(42);
    expect(future).toEqual(future);
    await expect(future).completion.toEqual(42);
    await expect(future).throws.isArgumentError();
  });

  test('stream example', () async {
    final stream = Stream.value(42);
    await expect(stream).emits.toEqual(42);
    await expect(stream).emits.isNull();
    await expect(stream).emits.not.isNull();
    await expect(stream).emitsError.isArgumentError();
  });

  test('function example', () {
    void throwsFn() => throw Error();
    expect(throwsFn).returnsNormally();
    expect(throwsFn).throws.isArgumentError();
  });
}

CLI

Installation

dart pub global activate spec_cli

Usage

Run tests:

spec

Run tests in interactive mode:

spec --watch

Interactive mode supports a number of keyboard shortcuts:

Watch Usage:
 › Press f to run only failed tests.
 › Press t to filter by a test name regex pattern.
 › Press q to quit watch mode.
 › Press Enter to trigger a test run.

GitHub Action

If you want to use Spec in your GitHub actions pipeline you can utilize the Spec GitHub action, instructions for how to use it can be found on the the spec-action's marketplace page and in its repository.

---

LICENSE

Built and maintained by Invertase.