Package selection guidance compiled from public package information, community data, and project usage.
Shouldly is a BDD-style assertion library for Dart and Flutter that prioritizes clear, descriptive error messages when tests fail. Designed to improve test readability and debugging efficiency, it offers a fluent API that reads like natural language. The library is extensible, allowing developers to customize assertions to fit specific project needs. It supports all major platforms including Android, iOS, Web, macOS, Windows, and Linux, making it ideal for cross-platform testing workflows.
Use cases
Writing readable and maintainable unit tests
Improving test failure diagnostics
Enhancing test-driven development workflows
Cross-platform testing with consistent assertions
Customizing assertion logic for domain-specific validation
Key features
Fluent, human-readable assertion syntax
Detailed and helpful error messages on failure
Extensible assertion system
Supports all Flutter platforms
Intuitive BDD-style API
Easy integration via pub add
Suitable for
Developers seeking better test feedback
Teams practicing TDD or BDD
Projects requiring clear test output
Cross-platform Flutter applications
Test automation engineers
Considerations
May require learning curve for new BDD users
Additional dependency in test suites
Limited to testing context (not runtime use)
Not suitable for production code assertions
Requires careful setup for custom assertions
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
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.
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
extensionCustomNumAssertionsonNumericAssertions {
NumericAssertionsget beNegative {
if (subject >= 0) {
throwShouldlyTestFailureError('Number\n should be negative');
}
returnNumericAssertions(subject);
}
}
Or more exotic matchers - fot custom types
First, create a Assertions class for your custom type which extends BaseAssertions
classCustomerAssertionsextendsBaseAssertions<Customer, CustomerAssertions> {
// ...CustomerAssertionsget beMarried {
if (isReversed) {
if (subject!.isMarried) {
throwShouldlyTestFailureError('Customer should not be married');
}
} else {
if (!subject!.isMarried) {
throwShouldlyTestFailureError('Customer should be married');
}
}
returnCustomerAssertions(subject);
}
CustomerAssertionsget 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');
returnCustomerAssertions(subject);
}
// ...
}
Second, create an extension on your class which has should property with type of your custom assertions class
extensionCustomerExtensiononCustomer {
CustomerAssertionsget should => CustomerAssertions(this);
}
Third, you are ready to go use your own shouldly assertions
test('async function should throw exception', () async {
awaitShould.throwAsync(() {
Future.delayed(Duration(milliseconds: 100));
throwException('test');
});
});
test('async function should throw exact exception', () async {
awaitShould.throwAsync<CustomException>(() {
Future.delayed(Duration(milliseconds: 100));
throwCustomException('custom exception test');
});
});
test('should complete in a duration', () async {
awaitShould.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>();
});
extensionCustomerExtensiononCustomer {
CustomerAssertionsget should => CustomerAssertions(this);
}
classCustomerAssertionsextendsBaseAssertions<Customer, CustomerAssertions> {
CustomerAssertions(
Customer? subject, {
bool isReversed = false,
String? subjectLabel,
}) : super(subject, isReversed: isReversed, subjectLabel: subjectLabel);
CustomerAssertionsget beMarried {
if (isReversed) {
if (subject!.isMarried) {
throwShouldlyTestFailure('Customer should not be married');
}
} else {
if (!subject!.isMarried) {
throwShouldlyTestFailure('Customer should be married');
}
}
returnCustomerAssertions(subject);
}
CustomerAssertionsget beMale {
if (isReversed) {
if (subject!.gender == Gender.male) {
throwShouldlyTestFailure('Customer should be female');
}
} else {
if (subject!.gender != Gender.male) {
throwShouldlyTestFailure('Customer should be male');
}
}
returnCustomerAssertions(subject);
}
@overrideCustomerAssertionscopy(
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.
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.