thespian v3.0.0

thespian

thespian is a mocking framework with a sophisticated approach to argument matching and providing useful error messages when arguments fail to match.

It is written in Typescript and respects types in mocks. It uses mismatched, a sophisticated composable matcher for matching arguments of method and function calls.

Thespians are like mocks - they play a role.

See Thespian By Example

See What is New

Short Docs:

• To create a Thespian in order to create mocks:
  • const thespian = new Thespian();
• To create a mock for a class or interface (with a given name, used in error messages):
  • const mockObject = thespian.mock<Check>("check");
  • To specify an expected method call:
    • mockObject.setup(c => c.match()).returns(() => 4);
  • To specify an expected method call to be called a specific number times:
    • mockObject.setup(c => c.match2("target")).returns(() => "ok").times(2);
  • To specify an expected method call throws an exception:
    • mockObject.setup(c => c.match2("target")).throws(new Error("failed"));
• To create a mock for an object property (with a given name, used in error messages):
  • const mockObject = thespian.mock<Check>("check");
  • To specify an expected property access:
    • mockObject.setup(c => c.prop).returns(() => 4);
  • To specify an expected property access to be called a specific number times:
    • mockObject.setup(c => c.prop).returns(() => 5).times(2);
  • To specify an expected property access results in an exception:
    • mockObject.setup(c => c.prop).throws("error");
• To create a mock for a function:
  • const mockFn = thespian.mock<(n: number)=>number>("fun");
  • To specify an expected function call:
    • mockFn.setup(f => f(5)).returns(() => 2);
  • To specify an expected function call to be called a specific number times:
    • mockFn.setup(f => f(100)).returns(() => 20).timesGreater(0);
  • To specify an expected function call results in an exception:
    • mockFn.setup(f => f(5)).throws("failed");
• To access the underlying mock for use in tests:
  • const check = mockCheck.object;
• To verify that all expected mock calls and property accesses have happened (usually in an afterEach()):
  • thespian.verify();

Mocked methods and function with the same arguments can return a series of results:

- To specify a mocked method call with the same arguments but different results (4 is returned in the first call, and 5 on the second):
  - `mockCheck.setup(c => c.match()).returns(() => 4);`
  - `mockCheck.setup(c => c.match()).returns(() => 5);`
- To specify a mocked property access with different results (4 is returned in the first call, and 5 on the second):
  - `mockCheck.setup(c => c.prop).returns(() => 4);`
  - `mockCheck.setup(c => c.prop).returns(() => 5);`
 - To specify a mocked method function with the same arguments but different results (4 is returned in the first call, and 5 on the second):
   - `mockCheck.setup(c => f(5)).returns(() => 4);`
   - `mockCheck.setup(c => f(5)).returns(() => 5);`

Possible returns:

• .returns(()=>45), a function that provides the result. The result can depend on the actual arguments. Eg, .returns((a,b) => a).
• .returnsVoid() for when the mocked method/function does not return a result.

Possible times checks:

• .times(), a specific number
• .timesAtLeast(), the minimum number of times
• .timesAtMost(), the maximum number of times

Possible throws:

• .throws(new Errow("failed")), a function that specifies that exception to be thrown when called. The result cannot depend on the actual arguments.

Example Error Message

When a call to a mocked method or function fails to match, it's useful to know whether there were any near misses. Here's an example, where there are two near misses:

Also see:

• See Thespian By Example
• See Mocks that throw
• See Thespian Design Decisions
• See Common Mocking Anti-Patterns
• See Lazy vs Eager Verification of Mocks
• See Mocks and Exception Handling in Tested Code