搜尋套件、儲存庫與 APP 分類

套件詳情v0.5.0+1

shouldly

一個簡單且可擴充的 BDD 斷言庫,專注於在斷言失敗時提供優秀的錯誤訊息。

AndroidiOSWebmacOSWindowsLinux
近 30 天下載
41
喜歡數
25
Pub 分數
140

安裝套件

flutter pub add shouldly

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

Shouldly 是一個用於 Dart 和 Flutter 的 BDD 風格斷言庫,它在測試失敗時優先提供清晰、描述性的錯誤訊息。此庫旨在提升測試的可讀性和除錯效率,提供一種類似自然語言的流暢 API。該庫具備可擴展性,允許開發者自訂斷言以符合特定專案需求。它支援所有主要平台,包括 Android、iOS、Web、macOS、Windows 和 Linux,使其非常適合跨平台測試工作流程。

適用情境

  • 編寫可讀且可維護的單元測試
  • 改進測試失敗診斷
  • 增強測試驅動開發工作流程
  • 跨平台測試與一致的斷言
  • 自定義領域特定驗證的斷言邏輯

主要特色

  • 流暢、易讀的斷言語法
  • 失敗時提供詳細且有幫助的錯誤訊息
  • 可擴充的斷言系統
  • 支援所有 Flutter 平台
  • 直覺式的 BDD 風格 API
  • 透過 pub add 輕鬆整合

適合對象

  • 尋求更好測試反饋的開發者
  • 實踐TDD或BDD的團隊
  • 需要明確測試輸出的專案
  • 跨平台 Flutter 應用程式
  • 測試自動化工程師

使用建議

  • 新用戶可能需要學習曲線
  • 測試套件中的附加依賴項
  • 僅限測試環境使用(不適用於執行時)
  • 不適合用於生產代碼斷言
  • 需要仔細設定自訂斷言

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

shouldly logo

pub package codecov likes style: lint Dart

shouldly is an assertion concept that focuses on

  • writing assertions as plain English sentences
  • and giving better error messages when the assertion fails while being simple and terse.

Inspired from Fluent Assertion, Shouldly, should.js

Features

  • More readable test code
  • Better test failure messages
  • Conjunction support (and)
  • Custom assertions

Better readability

More readable test code as plain English sentence.

void main() {
  const playerCharacter = PlayerCharacter(
    'Arthur',
    100,
    ['Axe', 'Sword', 'Staff of Wonder'],
  );

  test('equality', () {
    // non shouldly
    expect(playerCharacter.health, 100);
    // 😍 shouldly
    playerCharacter.health.should.be(100);
  });

  test('array contains', () {
    // non shouldly
    expect(playerCharacter.weapons, contains('Staff of Wonder'));
    // 😍 shouldly
    playerCharacter.weapons.should.contain('Staff of Wonder');
  });

  test('nullability of string', () {
    // non shouldly
    expect(playerCharacter.nickname, isNotNull);
    // 😍 shouldly
    playerCharacter.nickname.should.not.beNullOrEmpty();
  });
}

Better test failure messages

To get more readable and contextual information.

Non-Shouldly Shouldly
Expected: <10>
  Actual: <100>
Expected playerCharacter.health
    should be
10
    but was
100
Expected: null
  Actual: 'Arthur'
Expected nickname
    should be null or empty
but was
    `Arthur`
Expected: contains 'Staff of Wonderr'
  Actual: ['Axe', 'Sword', 'Staff of Wonder']
Expected playerCharacter.weapons
    should contain
Staff of Wonder
    but was actually
[Axe, Sword]

No more: Mix Up with parameters

You can mix up with Expected or Actual 🤔. But with shouldly there is no way to mix up.

// without shouldly
expect(playerCharacter.health, 0);
expect(0, playerCharacter.health);

// shouldly
playerCharacter.health.should.be(0);

No more single heap of assertion methods

Before

You could write such crazy assertions.

expect(2, isTrue);
expect(2, contains(2));
expect(2, startsWith('1'));
expect(2, isEmpty);
expect(2, throwsException);
After

Every single type of class has his own assertions. Easy to find required assertion method.

Conjunctions

This is a real English sentence, is it not?

13.should.beOdd().and.beGreaterOrEqualThan(13);
participants.should.contain('Andrew').and.not.contain('Bobby');

SatisfyAllConditions

satisfyAllConditions will show all errors at once, not only first fail assertion.

test('should satisfy all conditions', () {
    Should.satisfyAllConditions([
      () => playerCharacter.nickname.should.as('nickname').not.beNullOrEmpty(),
      () => playerCharacter.weapons.should.as('weapons').contain('Staff of Wonder'),
      () => playerCharacter.health.should.as('health').be(100),
    ]);
  });

Example report can be:

Expected satisfy all conditions specified, but does not.
The following errors were found ...

------------- Error 1 -------------
Expected nickname
    should not be null or empty
but was
    ''

------------- Error 2 -------------
Expected weapons
    should contain
Staff of Wonder
    but was actually
[Axe, Sword]

------------- Error 3 -------------
Expected health
    should be
100
    but was
99

------------------------------------

Custom matchers

For existing one - just create an extension for it
extension CustomNumAssertions on NumericAssertions {
  NumericAssertions get beNegative {
    if (subject >= 0) {
      throw ShouldlyTestFailureError('Number\n  should be negative');
    }
    return NumericAssertions(subject);
  }
}
Or more exotic matchers - fot custom types
  1. First, create a Assertions class for your custom type which extends BaseAssertions
class CustomerAssertions extends BaseAssertions<Customer, CustomerAssertions> {
  // ...

  CustomerAssertions get beMarried {
    if (isReversed) {
      if (subject!.isMarried) {
        throw ShouldlyTestFailureError('Customer should not be married');
      }
    } else {
      if (!subject!.isMarried) {
        throw ShouldlyTestFailureError('Customer should be married');
      }
    }
    return CustomerAssertions(subject);
  }

  CustomerAssertions get beMale {
    if (isReversed) {
      Execute.assertion
          .forCondition(subject!.gender == Gender.male)
          .failWith('$subjectLabel should not be male');
    } else {
      Execute.assertion
          .forCondition(subject!.gender != Gender.male)
          .failWith('$subjectLabel should be male');
    }

    Execute.assertion
        .forCondition(subject!.gender != Gender.male)
        .failWith('$subjectLabel should be male');

    return CustomerAssertions(subject);
  }

  // ...
}
  1. Second, create an extension on your class which has should property with type of your custom assertions class
extension CustomerExtension on Customer {
  CustomerAssertions get should => CustomerAssertions(this);
}
  1. Third, you are ready to go use your own shouldly assertions
test('Custom matchers', () {
  bobby.should.beMale.and.beMarried;
  kate.should.beMarried.and.not.beMale;
});

Complete in

To verify how long your function is executed

test('should complete in a duration', () async {
  await Should.completeIn(
    Duration(seconds: 1),
    func: () => slowFunction(
      Duration(milliseconds: 900),
    ),
  );
});

test('should complete after a period of time', () async {
  await Should.completeAfter(
    const Duration(seconds: 3),
    func: () => verySlowFunction(
      const Duration(seconds: 4),
    ),
  );
});

Getting started

Simple add shouldly dependency into your project.

dev_dependencies:
  shouldly: <latest>

Usage

Objects

Every single object has following assertion methods:

Method Example Failure message
be 1.should.be(2); Expected int should be 2 but was 1
beOfType 2.0.should.beOfType<double>();
beAssignableTo 3.should.beAssignableTo<int>();
beNull null.should.beNull();
beOneOf 5.should.beOneOf([1, 2, 5]);
test('should be not null', () {
  final obj = Object();
  obj.should.not.beNull();
});

test('should be null', () {
  const Object? obj = null;
  obj.should.beNull();
});

test('should be type of `int`', () {
  const obj = 1;
  obj.should.beOfType<int>();
});

test('should be assignable to `num`', () {
  const obj = 1;
  obj.should.beAssignableTo<num>();
});
Booleans
Method Example Failure message
beTrue false.should.beTrue(); Target boolean should be True but was False
beFalse false.should.not.beFalse(); Target boolean should not be False but was False
test('false should be `false`', () {
  false.should.beFalse();
});

test('false should not be `true`', () {
  false.should.not.beTrue();
});
Numbers
Method Example Failure message
bePositive (-1).should.bePositive(); Target int should be positive but was negative as -1
beNegative 1.should.beNegative(); Target int should be negative but was positive as 1
beZero 10.should.beZero(); Target int should be 0 but was 10
beOdd 8.should.beOdd(); Target int should be odd but was even as 8
beEven 7.should.beEven(); Target int should be event but was odd as 7
beGreaterThan 1.should.beGreaterThan(2); Target int should be greater than 2 but does not
beAbove 3.should.beAbove(2);
beLessThan 3.should.beLessThan(4);
beBelow 3.should.beBelow(4);
beGreaterOrEqualThan 3.should.beGreaterOrEqualThan(3);
beLessOrEqualThan 3.should.beLessOrEqualThan(3);
beWithin 3.should.beWithin(1,5);
beCloseTo pi.should.beCloseTo(3.14, delta: 0.01);
beTolerantOf pi.should.beTolerantOf(3.14, tolerance: 1%);
test('Int should be type of `int`', () {
  2.should.beEven();
  10.should.beGreaterThan(9);
  9.99.should.not.beCloseTo(10.0, delta: 0.01);
});
Strings
Method Example Failure message
startWith 'Flutter'.should.startWith('f');
endWith 'Flutter'.should.endWith('a');
haveLength 'Flutter'.should.haveLength(10);
beNullOrEmpty 'Flutter'.should.beNullOrEmpty();
beNullOrWhiteSpace 'Flutter'.should.beNullOrWhiteSpace();
beBlank 'Flutter'.should.beBlank();
match 'Flutter'.should.match('*a');
contain 'Flutter'.should.contain('a');
test('should not start with substring', () {
  'Flutter'.should.not.startWith('A');
});
DateTimes
Method Example Failure message
beCloseTo DateTime.now().should.beCloseTo(Date(2025, 1, 1));
beAfter DateTime.now().should.beCloseTo(Date(2022, 1, 1));
beBefore DateTime.now().should.beBefore(Date(2222, 1, 1));
// before
DateTime(2021, 9, 9).should.beBefore(DateTime(2021, 9, 10));
DateTime(2021, 9, 9).should.not.beBefore(DateTime(2021, 9, 9));

// close to
DateTime(2021, 9, 9, 1, 1, 1, 2).should.beCloseTo(
      DateTime(2021, 9, 9, 1, 1, 1, 3),
      delta: Duration(milliseconds: 1),
    );
Iterables
Method Example Failure message
haveCount [1, 2, 3].should.haveCount(7);
contain [1, 2, 3].should.contain(7);
containAll [1, 2, 3].should.containAll([7, 8]);
every [1, 2, 3].should.every((x) => x > 10);
any [1, 2, 3].should.any((x) => x == 0);
test('should contain', () {
  [1, 200, 3].should.contain(200);
});

test('should not contain', () {
  [1, 2, 4].should.not.contain(3);
});

test('with every element in collection is true for predicate', () {
  [3, 5, 7, 9].should.every((item) => item < 10);
});

test('with some elements in collection is true for predicate', () {
  [3, 5, 7, 9].should.any((item) => item > 8);
});
Maps
Method Example Failure message
haveCount {}.should.haveCount(7);
beEmpty {}.should.beEmpty();
containKey {'name': 'Bobby'}.should.containKey('age');
containKeys {}.should.containKeys(['age', 'name']);
haveValueInKey {}.should.haveValueInKey('name');
containKeyWithValue {}.should.containKeyWithValue('name', 'Bobby');
contain {}.should.haveValueInKey(<MapEntry>[]);
final subject = {
  'name': 'John',
  'age': 18,
};

test('should contain key', () {
  subject.should.containKey('name');
});

test('should contain key with exact value', () {
  subject.should.containKeyWithValue('age', 18);
});
Functions
Method Example Failure message
throwException Should.throwException(() => myFunc());
notThrowException Should.notThrowException(() => myFunc());
throwError Should.throwError(() => myFunc());
notThrowError Should.notThrowError(() => myFunc());
completeIn Should.completeIn(Duration(seconds: 1), () => myFunc());
Should.throwException(() => someMethodWitchThrowException(params:));
Should.throwError<ExactError>(() => someMethodWitchThrowExactError(params:));
test('async function should throw exception', () async {
  await Should.throwAsync(() {
    Future.delayed(Duration(milliseconds: 100));
    throw Exception('test');
  });
});

test('async function should throw exact exception', () async {
  await Should.throwAsync<CustomException>(() {
    Future.delayed(Duration(milliseconds: 100));
    throw CustomException('custom exception test');
  });
});

test('should complete in a duration', () async {
  await Should.completeIn(
    Duration(seconds: 1),
    func: () => slowFunction(
      Duration(milliseconds: 900),
    ),
  );
});
Enums
test('should not be equal', () {
  seasons.spring.should.not.be(seasons.winter);
});

test('should not be type of', () {
  seasons.spring.should.not.beOfType<level>();
});

test('should be assignable to `Enum`', () {
  seasons.spring.should.beAssignableTo<Enum>();
});

More examples here

Writing Custom Matchers

extension CustomerExtension on Customer {
  CustomerAssertions get should => CustomerAssertions(this);
}

class CustomerAssertions extends BaseAssertions<Customer, CustomerAssertions> {
  CustomerAssertions(
    Customer? subject, {
    bool isReversed = false,
    String? subjectLabel,
  }) : super(subject, isReversed: isReversed, subjectLabel: subjectLabel);

  CustomerAssertions get beMarried {
    if (isReversed) {
      if (subject!.isMarried) {
        throw ShouldlyTestFailure('Customer should not be married');
      }
    } else {
      if (!subject!.isMarried) {
        throw ShouldlyTestFailure('Customer should be married');
      }
    }
    return CustomerAssertions(subject);
  }

  CustomerAssertions get beMale {
    if (isReversed) {
      if (subject!.gender == Gender.male) {
        throw ShouldlyTestFailure('Customer should be female');
      }
    } else {
      if (subject!.gender != Gender.male) {
        throw ShouldlyTestFailure('Customer should be male');
      }
    }

    return CustomerAssertions(subject);
  }

  @override
  CustomerAssertions copy(
    Customer? subject, {
    bool isReversed = false,
    String? subjectLabel,
  }) =>
      CustomerAssertions(
        subject,
        isReversed: isReversed,
        subjectLabel: subjectLabel,
      );
}

Recommendations

You can improve the readability of the rest of your test code with given_when_then_unit_test, which enhances the test report readability as well.

drawing

Changelog

Please see the Changelog page to know what's recently changed.

Contributing

Feel free to contribute to this project.

If you find a bug or want a feature, but don't know how to fix/implement it, please fill an issue.
If you fixed a bug or implemented a new feature, please send a pull request.

We accept the following contributions:

  • Ideas how to improve
  • Reporting issues
  • Fixing bugs
  • More tests
  • More class integrations (Functions, Futures, Streams, Durations)
  • Improving documentation and comments

Maintainers

  • [Andrew Piterov](mailto:contact@andrewpiterov.com?subject=[GitHub]%20Source%20Dart%20shouldly)

所屬分類

依賴

依賴清單 1 項

原始碼儲存庫

使用此套件的專案