Merge pull request #239 from sgtoj/improve-ts

Improve TS Support

Author: searls

index.d.ts

@@ -1,82 +1,235 @@
-export type TestDouble = Function;
+//
+// types and interfaces
+// ----------------------------------------------------------------------------
 
-export type DoubledObjectWithKey<Key extends string> = {};
+export type DoubledObject<T> = T;
 
-export type DoubledObject<Subject> = Subject;
+export type DoubledObjectWithKey<T extends string> = { [K in T] };
 
-export interface TestdoubleConfig {
-  promiseConstructor?: any;
-  ignoreWarnings?: boolean;
-  suppressErrors?: boolean;
-}
-export function config(config: TestdoubleConfig): void;
-
-declare function functionDouble(name?: string): TestDouble;
-export { functionDouble as function };
+export type TestDouble<T> = T;
 
-// When passed class or constructor function
-export function object<T>(constructor: { new (...args: any[]): T }): DoubledObject<T>;
+export type TestDoubleConstructor<T> = Constructor<T>;
 
-// When passed array of props
-export function object<Key extends string>(props: Key[]): DoubledObjectWithKey<Key>;
-
-// When passed class or constuctor function name as string value
-export function object<T>(object: string): DoubledObject<T>;
-
-// When passed general object
-export function object<T>(object: T): DoubledObject<T>;
+interface Call {
+  context: {};
+  args: any[];
+}
 
-export interface Stubber {
-  thenReturn(...args: any[]): TestDouble;
-  thenDo(f: Function): TestDouble;
-  thenThrow(e: Error): TestDouble;
-  thenResolve(...args: any[]): TestDouble;
-  thenReject(e: Error): TestDouble;
-  thenCallback(...args: any[]): TestDouble;
+interface Constructor<T> {
+  new (...args: any[]): T
 }
 
-export function callback(...args: any[]): void;
+export interface Captor {
+  capture(): any;
+  value?: any;
+  values?: any[];
+}
 
-export function when(...args: any[]): Stubber;
+export interface Explanation {
+  callCount: number;
+  calls: Call[];
+  description: string;
+}
 
 export interface Matchers {
   anything(): any;
   isA(type: Function): any;
-  contains(a: string|any[]|{}): any;
+  contains(a: string | any[] | {}): any;
   argThat(matcher: Function): any;
   not(v: any): any;
   captor(): Captor
 }
 
-export interface Captor {
-  capture(): any;
-  value?: any;
-  values?: any[];
-}
-
 export const matchers: Matchers;
 
-export function replace(path: string, f?: any): any;
-export function replace(path: {}, property: string, f?: any): any;
+export interface Stubber {
+  thenReturn<T>(...args: any[]): TestDouble<T>;
+  thenDo<T>(f: Function): TestDouble<T>;
+  thenThrow<T>(e: Error): TestDouble<T>;
+  thenResolve<T>(...args: any[]): TestDouble<T>;
+  thenReject<T>(e: Error): TestDouble<T>;
+  thenCallback<T>(...args: any[]): TestDouble<T>;
+}
 
-export function reset(): void;
+export interface TestdoubleConfig {
+  promiseConstructor?: any;
+  ignoreWarnings?: boolean;
+  suppressErrors?: boolean;
+}
 
 export interface VerificationConfig {
   ignoreExtraArgs?: boolean;
   times?: number;
 }
 
-export function verify(a: any, check?: VerificationConfig): void;
+//
+// general
+// ----------------------------------------------------------------------------
+
+/**
+ * Update the configuration. Configuration will perist through the lifetime of
+ * of the entire test. If you need to change a configuration property for a
+ * single test, you'll need to manage undoing the change yourself (e.g. in
+ * beforeEach and afterEach hooks).
+ *
+ * @export
+ * @param {TestdoubleConfig} config
+ */
+export function config(config: TestdoubleConfig): void;
 
-interface Call {
-  context: {};
-  args: any[];
-}
+/**
+ * Reset the state.
+ *
+ * @export
+ */
+export function reset(): void;
 
-export interface Explanation {
-  callCount: number;
-  calls: Call[];
-  description: string;
-}
+/**
+ * Takes a test double function as an argument and will describe the current
+ * configuration and state of the test double.
+ *
+ * @export
+ * @template T
+ * @param {TestDouble<T>} f
+ * @returns {Explanation}
+ */
+export function explain<T>(f: TestDouble<T>): Explanation;
+
+
+//
+// fake: constructors
+// ----------------------------------------------------------------------------
+
+/**
+ * Create a fake object constructor the given class.
+ *
+ * @export
+ * @template T
+ * @param {{ new (...args: any[]): T }} constructor
+ * @returns {DoubledObject<T>}
+ */
+export function constructor<T>(constructor: Constructor<T>): TestDoubleConstructor<T>;
+
+//
+// fake: functions
+// ----------------------------------------------------------------------------
+
+/**
+ * Create a fake function.
+ *
+ * @param {string} [name] Name of function for better messages.
+ * @returns {TestDouble<Function>}
+ */
+declare function functionDouble(name?: string): TestDouble<Function>;
+
+/**
+ * Create a fake function.
+ *
+ * @template T
+ * @param {T} [name] Name of function to copy.
+ * @returns {TestDouble<T>}
+ */
+declare function functionDouble<T>(name?: T): TestDouble<T>;
 
-export function explain(f: TestDouble): Explanation;
+export { functionDouble as function };
+export { functionDouble as func };
+
+//
+// fake: objects
+// ----------------------------------------------------------------------------
+
+/**
+ * Create a fake object that is deep copy of the given object.
+ *
+ * @export
+ * @template T
+ * @param {{ new (...args: any[]): T }} constructor
+ * @returns {DoubledObject<T>}
+ */
+export function object<T>(constructor: Constructor<T> ): DoubledObject<T>;
+
+/**
+ * Create a fake object that has the given list of properties.
+ *
+ * @export
+ * @template Key
+ * @param {Key[]} props Array of properties.
+ * @returns {DoubledObjectWithKey<Key>}
+ */
+export function object<T extends string>(props: T[]): DoubledObjectWithKey<T>;
+
+/**
+ * Create a fake empty object that is cast as the generic using a Proxy object.
+ *
+ * @export
+ * @template T
+ * @param {T} object Name of object.
+ * @returns {DoubledObject<T>}
+ */
+export function object<T>(object: string): DoubledObject<T>;
+
+/**
+ * Create a fake object that is deep copy of the given object.
+ *
+ * @export
+ * @template T
+ * @param {T} object Object to copy.
+ * @returns {DoubledObject<T>}
+ */
+export function object<T>(object: T): DoubledObject<T>;
+
+//
+// stubbing
+// ----------------------------------------------------------------------------
+
+
+/**
+ * Callback marker.
+ *
+ * @export
+ * @param {...any[]} args
+ */
+export function callback(...args: any[]): void;
+
+
+/**
+ * Swap out real dependenencies with fake one. Intercept calls to `require`
+ * that dependency module and ensure your subject is handed a fake instead.
+ *
+ * @export
+ * @param {string} path
+ * @param {*} [f]
+ * @returns {*}
+ */
+export function replace(path: string, f?: any): any;
+
+/**
+ * Swap out real dependenencies with fake one. Reference to the property will
+ * be replace it during your test.
+ *
+ * @export
+ * @param {{}} path
+ * @param {string} property
+ * @param {*} [f]
+ * @returns {*}
+ */
+export function replace(path: {}, property: string, f?: any): any;
+
+
+/**
+ * Stub a specific function call.
+ *
+ * @export
+ * @param {...any[]} args
+ * @returns {Stubber}
+ */
+export function when(...args: any[]): Stubber;
+
+/**
+ * Verify a specific function call to a stubbed function.
+ *
+ * @export
+ * @param {...any[]} args
+ * @returns {Stubber}
+ */
+export function verify(a: any, check?: VerificationConfig): void;

regression/typescript/test.ts

@@ -8,12 +8,26 @@ class Dog {
   bark() {}
 }
 
+class Cat {
+  constructor() {};
+  meow(): string { return "meow! meow!" }
+}
+
+function sum (first: number, second: number): number {
+  return first + second
+}
+
+
 const dog = td.constructor(Dog);
 td.when(dog.prototype.bark()).thenReturn("woof!");
 
 const bird = td.object({ fly: function(){} });
 td.when(bird.fly()).thenReturn("swoosh!");
 
+const kitty = td.object(["scratch","meow"]);
+td.when(kitty.scratch()).thenReturn("scratch!");
+td.when(kitty.meow()).thenReturn("meow!");
+
 if (eval("typeof Proxy") !== "undefined") {
   class Bear { constructor() {}; sleep() {}; };
   const bear = td.object<Bear>("A bear");
@@ -36,12 +50,22 @@ td.when(f(td.matchers.isA(String))).thenDo(function(s: string) { return s; });
 td.when(f(td.matchers.not(true))).thenResolve("value1", "value2");
 td.when(f(td.matchers.not(false))).thenReject(new Error("rejected"));
 
+const fakeSum = td.function(sum);
+td.when(fakeSum(1, 2)).thenReturn(3);
+
+const fakestSum = td.function("sum");
+td.when(fakestSum(1, 2)).thenReturn(3);
+
 f()
 td.verify(f());
 td.verify(f(), { times: 1 });
 td.verify(f(), { ignoreExtraArgs: false });
 td.verify(f(), { ignoreExtraArgs: true, times: 1 });
 
+const CatFake = td.constructor(Cat);
+const cat = new CatFake()
+td.when(cat.meow()).thenReturn("moo!");
+
 const explanation = td.explain(f);
 
 console.log(