{"id":15293099,"url":"https://github.com/akushwarrior/should","last_synced_at":"2025-04-13T12:28:43.840Z","repository":{"id":56839071,"uuid":"283947750","full_name":"AKushWarrior/should","owner":"AKushWarrior","description":"A BDD-style assertion library for Dart.","archived":false,"fork":false,"pushed_at":"2020-08-08T18:12:37.000Z","size":36,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T12:28:36.436Z","etag":null,"topics":["assert","assertion","assertion-library","bdd","dart","flutter","hamcrest","should","test","testing"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/should","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AKushWarrior.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-31T05:09:41.000Z","updated_at":"2022-01-22T10:38:40.000Z","dependencies_parsed_at":"2022-08-29T05:00:46.852Z","dependency_job_id":null,"html_url":"https://github.com/AKushWarrior/should","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AKushWarrior%2Fshould","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AKushWarrior%2Fshould/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AKushWarrior%2Fshould/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AKushWarrior%2Fshould/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AKushWarrior","download_url":"https://codeload.github.com/AKushWarrior/should/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248713713,"owners_count":21149751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assert","assertion","assertion-library","bdd","dart","flutter","hamcrest","should","test","testing"],"created_at":"2024-09-30T16:39:48.369Z","updated_at":"2025-04-13T12:28:43.819Z","avatar_url":"https://github.com/AKushWarrior.png","language":"Dart","readme":"A BDD-style assertion library for Dart developers. It has built-in support for most \ncommon primitives, including Strings, Numbers Functions, Iterables. It also\nhas type and equality checks built in for all objects.\n\nshould is currently in production use in 4 of my projects, and is part of a larger testing framework. This\nframework is un-named and under development for open-sourcing. should will, upon that package's release, be\navailable both bundled and independently. \n\n## Usage\nshould is based on OO chains; at the end of the assertion, a reflective operation captures each 'section' of the \nassertion. A simple example:\n\n```dart\nimport 'package:should/should.dart';\n\nmain() {\n  var dou = 2.0;\n\n  requireThat(dou).be\u003cint\u003e(); //oops, doubles aren't int --\u003e error\n\n  //but we can put in our own logic --\u003e No error\n  unless(dou is double).requireThat(dou).be\u003cint\u003e();\n\n  //doubles are not subclass of int --\u003e No error\n  requireThat(dou).not.beSubclassOf\u003cint\u003e();\n\n  // There is three options for type checking:\n  // dou.should.be\u003cint\u003e is equivalent to: assert(dou is int).\n  // dou.should.beSubclass (dou is an instance of a subclass of given type)\n  // or dou.should.instantiate (dou is a direct instance of given type).\n\n  //2.0 == 2.0 \u0026\u0026 2.0 != 0--\u003e No error\n  requireThat(dou).equal(2.0).and.not.equalAllOf([0, 1, 2, 3, 4]);\n\n  print('evaluated 4 should statements');\n}\n```\n\n## Matchers\nshould has specific matchers beyond the general matchers displayed above. (It also has a few other general matchers not\nshown above). These are imported through specific libraries. For instance, if I wanted matchers for numbers as well as \nStrings, I would import:\n```dart\nimport 'package:should/should.dart';\nimport 'package:should/should_num.dart';\nimport 'package:should/should_string.dart';\n```\nDocumentation for all the matchers will come soon. For now, you can check the API reference all the available matchers (\n`Cap` is our name for matchers). \n\nMatchers are currently available for: Numbers, Strings, Zero-parameter functions, and Iterables.\nMatchers are planned for: Parameterized spies, Streams, and Futures.\n\nFile an issue if you think there's a matcher type we should support! Or, write your own (see below)!\n\n## Writing Custom Matchers\nTo write a custom matcher, you'll have to write an extension over BaseShouldObject. Suppose we wanted to check if a num\nis negative. We would write an extension like this:\n```dart\nextension ShouldNumExtension on BaseShouldObject\u003cnum\u003e {\n  Cap\u003cnum\u003e get beNegative {\n    var cap = Cap\u003cnum\u003e((obj) {\n      num n = obj as num; //cast dynamic object to num\n      return n \u003c 0;\n    }, this, 'be negative');\n    finalEval(cap);\n    return cap;\n  }\n}\n```\nThere's a few critical pieces here. the declaration starting with `var cap =` is creating a `Cap` object, which is the\ninternal representation of a matcher. Cap takes three parameters: a `bool Function(dynamic)`, a `BaseShouldObject`, and\na `String`. The first is your business logic, as seen above. The second is internal; it should **always be `this`**. The last\nis the debugging description of this matcher. Imagine the matcher in a sentence to come up with this: `2 should (be negative)`.\nTo adapt this sample to another type is easy: simply replace the word `num` wherever it appears with your own type.\n\nWe could then use our matcher anywhere that both 'package:should/should.dart' and the extension from above have been imported.\n```dart\nrequireThat(-2).beNegative;\n```\n\n## should vs. assert\nshould is meant to be used as a drop-in replacement for `assert`. If assert\nwould not throw an error, this library does not either. However, this library will print\nshort error messages to the console regardless of whether assertions are enabled.\n\nThis library, in my opinion, is also easier to read than an arbitrary assertion. It follows\nthe laws of English, which are easier to read intuitively than mathematical lingo.\n\nshould additionally has cleaner outputs to the terminal, using some hardcoded psuedo-introspection\n to determine what a failed assertion was attempting to do. For example, the assertion:\n\n```dart\n2.0.should.beType\u003cint\u003e();\n```\nfails in should with the error message:\n`Your should assertion failed on line 10: 2.0 should be Type int`, as well as a StackTrace. assert would just give you \nthe StackTrace. Note that all stacktraces aren't created equal; take a look at a sample I've compiled for assert:\n\n```\nUnhandled exception:\n'file:///home/___/___/should/example/generic_example.dart': Failed assertion: line 11 pos 10: 'dou is int': is not true.\n#0      _AssertionError._doThrowNew (dart:core-patch/errors_patch.dart:42:39)\n#1      _AssertionError._throwNew (dart:core-patch/errors_patch.dart:38:5)\n#2      genericExample (file:///home/akishore/IdeaProjects/should/example/generic_example.dart:11:10)\n#3      main (file:///home/akishore/IdeaProjects/should/example/generic_example.dart:5:3)\n#4      _startIsolate.\u003canonymous closure\u003e (dart:isolate-patch/isolate_patch.dart:301:19)\n#5      _RawReceivePortImpl._handleMessage (dart:isolate-patch/isolate_patch.dart:168:12)\n```\nvs. should for the equivalent call:\n```\n┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n│ Your should assertion failed on line 11: 2.0 should be Type int\n│ See the StackTrace below for more details...\n└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\nexample/generic_example.dart 11:14              genericExample\nexample/generic_example.dart 5:3                main\n```\n\nJust like with assert, you can enable or disable error-throwing. Use `should.errorOnAssert = true;` to make should throw\nerrors on failed assertions. Unfortunately, if this is set to true, then you will lose the enhanced, terse StackTraces\nfrom above.\n\n## should vs. expect\n`expect` is the assertion method for the built in testing library (https://pub.dev/packages/test). should *will* work in\n these tests, but only if you set `should.errorOnAssert = true`. should will still print the first error message (the \n introspective one starting with \"Your should assertion failed...), but you'll lose the terse stacktrace in exchange for\n whatever the test package gives you.\n \n should vs. expect, on a functional level, are fairly similar. It is mostly a stylistic difference: expect uses a\n Unit Test Matcher style, whereas should uses a BDD style. BDD is more readable but less concise than the style expect\n uses.\n\n## TODO: Where We're Heading\n- More tests\n- Conjunction support (see: should.js and/or) (`and` conjunctions complete)\n- More class integrations (Streams? Futures?)\n- Cleaner code documentation and comments\n- Simple Spies\n\n## Features and bugs\n\nPlease file feature requests and bugs at the [issue tracker][tracker].\n\n[tracker]: https://github.com/AKushWarrior/should/issues\n\n###### This library is licensed under the MPL 2.0.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakushwarrior%2Fshould","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakushwarrior%2Fshould","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakushwarrior%2Fshould/lists"}