expect

What is expect?

The 'expect' npm package is a library for writing test assertions. It is commonly used in conjunction with testing frameworks like Jest or Mocha to validate the behavior of JavaScript code. It provides a range of assertion types and matchers that allow developers to write expressive and readable tests.

What are expect's main functionalities?

Basic Assertions

This feature allows you to assert that a value matches exactly what you expect. The 'toBe' matcher compares with ===.

expect(2 + 2).toBe(4);

Object Property Assertions

With this feature, you can assert that an object has a specific property with a certain value. The 'toHaveProperty' matcher checks for the existence and value of a property in an object.

expect({ name: 'Alice', age: 30 }).toHaveProperty('name', 'Alice');

Exception Testing

This feature is used to test if a function throws an exception when it is executed. The 'toThrow' matcher is used to assert that an error is thrown with a specific message.

expect(() => { throw new Error('failure'); }).toThrow('failure');

Array Containment

This feature allows you to assert that an array contains a specific item. The 'toContain' matcher checks if an array includes the expected item.

expect(['Alice', 'Bob', 'Eve']).toContain('Bob');

Asynchronous Assertions

This feature enables you to write assertions for asynchronous code. The 'resolves' matcher waits for a promise to resolve and then checks the resolved value.

expect(Promise.resolve('success')).resolves.toBe('success');

Other packages similar to expect

chai

Chai is a BDD/TDD assertion library for node and the browser that can be paired with any javascript testing framework. It offers a similar range of matchers and assertions as expect, and it provides a fluent chainable language to construct assertions.

should

Should.js is an expressive, readable, framework-agnostic assertion library. The key difference is in the style of assertions it offers, using a more fluent chainable API that reads like English.

assert

Assert is a module that provides a set of assertion functions for verifying invariants. It is built into Node.js and is less feature-rich compared to expect, but it serves as a simple way to write assertions in a Node.js environment.

jest

Jest is a delightful JavaScript Testing Framework with a focus on simplicity. It comes with its own assertion library, which provides functionality similar to expect, as expect is actually part of Jest.

README

The README file is missing

Changelog

jest 21.0.0

• Add --changedFilesWithAncestor (#4070)

• Add --findRelatedFiles (#4131)

• Add --onlyChanged tests (#3977)

• Add contextLines option to jest-diff (#4152)

• Add alternative serialize API for pretty-format plugins (#4114)

• Add displayName to MPR (#4327)

• Add displayName to TestResult (#4408)

• Add es5 build of pretty-format (#4075)

• Add extra info to no tests for changed files message (#4188)

• Add fake chalk in browser builds in order to support IE10 (#4367)

• Add jest.requireActual (#4260)

• Add maxWorkers to globalConfig (#4005)

• Add skipped tests support for jest-editor-support (#4346)

• Add source map support for better debugging experience (#3738)

• Add support for Error objects in toMatchObject (#4339)

• Add support for Immutable.Record in pretty-format (#3678)

• Add tests for extract_requires on export types (#4080)

• Add that toMatchObject can match arrays (#3994)

• Add watchPathIgnorePatterns to exclude paths to trigger test re-run in watch mode (#4331)

• Adding ancestorTitles property to JSON test output (#4293)

• Allow custom resolver to be used with[out] moduleNameMapper (#4174)

• Avoid parsing .require(…) method calls (#3777)

• Avoid unnecessary function declarations and call in pretty-format (#3962)

• Avoid writing to stdout in default reporter if --json is enabled. Fixes #3941 (#3945)

• Better error handling for --config (#4230)

• Call consistent pretty-format plugins within Jest (#3800)

• Change babel-core to peerDependency for compatibility with Babel 7 (#4162)

• Change Promise detection code in jest-circus to support non-global Promise implementations (#4375)

• Changed files eager loading (#3979)

• Check whether we should output to stdout or stderr (#3953)

• Clarify what objects toContain and toContainEqual can be used on (#4307)

• Clean up resolve() logic. Provide useful names for variables and functions. Test that a directory exists before attempting to resolve files within it. (#4325)

• cleanupStackTrace (#3696)

• compare objects with Symbol keys (#3437)

• Complain if expect is passed multiple arguments (#4237)

• Completes nodeCrawl with empty roots (#3776)

• Consistent naming of files (#3798)

• Convert code base to ESM import (#3778)

• Correct summary message for flag --findRelatedTests. (#4309)

• Coverage thresholds can be set up for individual files (#4185)

• custom reporter error handling (#4051)

• Define separate type for pretty-format plugin Options (#3802)

• Delete confusing async keyword (#3679)

• Delete redundant branch in ReactElement and HTMLElement plugins (#3731)

• Don't format node assert errors when there's no 'assert' module (#4376)

• Don't print test summary in --silent (#4106)

• Don't try to build ghost packages (#3934)

• Escape double quotes in attribute values in HTMLElement plugin (#3797)

• Explain how to clear the cache (#4232)

• Factor out common code for collections in pretty-format (#4184)

• Factor out common code for markup in React plugins (#4171)

• Feature/internal resolve (#4315)

• Fix --logHeapUsage (#4176)

• Fix --showConfig to show all project configs (#4078)

• Fix --watchAll (#4254)

• Fix bug when setTimeout is mocked (#3769)

• Fix changedFilesWithAncestor (#4193)

• Fix colors for expected/stored snapshot message (#3702)

• Fix concurrent test failure (#4159)

• Fix for 4286: Compare Maps and Sets by value rather than order (#4303)

• fix forceExit (#4105)

• Fix grammar in React Native docs (#3838)

• Fix inconsistent name of complex values in pretty-format (#4001)

• Fix issue mocking bound method (#3805)

• Fix jest-circus (#4290)

• Fix lint warning in main

  (#4132)

• Fix linting (#3946)

• fix merge conflict (#4144)

• Fix minor typo (#3729)

• fix missing console.log messages (#3895)

• fix mock return value (#3933)

• Fix mocking for modules with folders on windows (#4238)

• Fix NODE_PATH resolving for relative paths (#3616)

• Fix options.moduleNameMapper override order with preset (#3565 (#3689)

• Fix React PropTypes warning in tests for Immutable plugin (#4412)

• Fix regression in mockReturnValueOnce (#3857)

• Fix sample code of mock class constructors (#4115)

• Fix setup-test-framework-test (#3773)

• fix typescript jest test crash (#4363)

• Fix watch mode (#4084)

• Fix Watchman on windows (#4018)

• Fix(babel): Handle ignored files in babel v7 (#4393)

• Fix(babel): Support upcoming beta (#4403)

• Fixed object matcher (#3799)

• Fixes #3820 use extractExpectedAssertionsErrors in jasmine setup

• Flow upgrade (#4355)

• Force message in matchers to always be a function (#3972)

• Format describe and use test instead of it alias (#3792)

• global_config.js for multi-project runner (#4023)

• Handle async errors (#4016)

• Hard-fail if hasteImpl is throwing an error during initialization. (#3812)

• Ignore import type for extract_requires (#4079)

• Ignore indentation of data structures in jest-diff (#3429)

• Implement 'jest.requireMock' (#4292)

• Improve Jest phabricator plugin (#4195)

• Improve Seq and remove newline from non-min empty in Immutable plugin (#4241)

• Improved the jest reporter with snapshot info per test. (#3660)

• Include fullName in formattedAssertion (#4273)

• Integrated with Yarn workspaces (#3906)

• jest --all (#4020)

• jest-circus test failures (#3770)

• jest-circus Timeouts (#3760)

• jest-haste-map: add test case for broken handling of ignore pattern (#4047)

• jest-haste-map: add test+fix for broken platform module support (#3885)

• jest-haste-map: deprecate functional ignorePattern and use it in cache key (#4063)

• jest-haste-map: mock 'fs' with more idiomatic jest.mock() (#4046)

• jest-haste-map: only file IO errors should be silently ignored (#3816)

• jest-haste-map: throw when trying to get a duplicated module (#3976)

• jest-haste-map: watchman crawler: normalize paths (#3887)

• jest-runtime: atomic cache write, and check validity of data (#4088)

• Join lines with newline in jest-diff (#4314)

• Keep ARGV only in CLI files (#4012)

• let transformers adjust cache key based on mapCoverage (#4187)

• Lift requires (#3780)

• Log stack when reporting errors in jest-runtime (#3833)

• Make --listTests return a new line separated list when not using --json (#4229)

• Make build script printing small-terminals-friendly (#3892)

• Make error messages more explicit for toBeCalledWith assertions (#3913)

• Make jest-matcher-utils use ESM exports (#4342)

• Make jest-runner a standalone package. (#4236)

• Make Jest’s Test Runner configurable. (#4240)

• Make listTests always print to console.log (#4391)

• Make providesModuleNodeModules ignore nested node_modules directories

• Make sure function mocks match original arity (#4170)

• Make sure runAllTimers also clears all ticks (#3915)

• Make toBe matcher error message more helpful for objects and arrays (#4277)

• Make useRealTimers play well with timers: fake (#3858)

• Move getType from jest-matcher-utils to separate package (#3559)

• Multiroot jest-change-files (#3969)

• Output created snapshot when using --ci option (#3693)

• Point out you can use matchers in .toMatchObject (#3796)

• Prevent babelrc package import failure on relative current path (#3723)

• Print RDP details for windows builds (#4017)

• Provide better error checking for transformed content (#3807)

• Provide printText and printComment in markup.js for HTMLElement plugin (#4344)

• Provide regex visualization for testRegex (#3758)

• Refactor CLI (#3862)

• Refactor names and delimiters of complex values in pretty-format (#3986)

• Replace concat(Immutable) with Immutable as item of plugins array (#4207)

• Replace Jasmine with jest-circus (#3668)

• Replace match with test and omit redundant String conversion (#4311)

• Replace print with serialize in AsymmetricMatcher plugin (#4173)

• Replace print with serialize in ConvertAnsi plugin (#4225)

• Replace print with serialize in HTMLElement plugin (#4215)

• Replace print with serialize in Immutable plugins (#4189)

• Replace unchanging args with one config arg within pretty-format (#4076)

• Return UNDEFINED for undefined type in ReactElement plugin (#4360)

• Rewrite some read bumps in pretty-format (#4093)

• Run update method before installing JRE on Circle (#4318)

• Separated the snapshot summary creation from the printing to improve testability. (#4373)

• Set coverageDirectory during normalize phase (#3966)

• Setup custom reporters after default reporters (#4053)

• Setup for Circle 2 (#4149)

• Simplify readme (#3790)

• Simplify snapshots definition (#3791)

• skipNodeResolution config option (#3987)

• Small fixes to toHaveProperty docs (#3878)

• Sort attributes by name in HTMLElement plugin (#3783)

• Specify watchPathIgnorePatterns will only be available in Jest 21+ (#4398)

• Split TestRunner off of TestScheduler (#4233)

• Strict and explicit config resolution logic (#4122)

• Support maxDepth option in React plugins (#4208)

• Support SVG elements in HTMLElement plugin (#4335)

• Test empty Immutable collections with {min: false} option (#4121)

• test to debug travis failure in main (#4145)

• testPathPattern message test (#4006)

• Throw Error When Using Nested It Specs (#4039)

• Throw when moduleNameMapper points to inexistent module (#3567)

• Unified 'no tests found' message for non-verbose MPR (#4354)

• Update migration guide with jest-codemods transformers (#4306)

• Use "inputSourceMap" for coverage re-mapping. (#4009)

• Use "verbose" no test found message when there is only one project (#4378)

• Use babel transform to inline all requires (#4340)

• Use eslint plugins to run prettier (#3971)

• Use iterableEquality in spy matchers (#3651)

• Use modern HTML5 <!DOCTYPE> (#3937)

• Wrap Error.captureStackTrace in a try (#4035)