Promise Puppeteer
Table Of Contents
- Section 1: Introduction
- Section 2: Setup
- Section 3: Test Examples
- Section 4: PromiseFake and Thenable APIs
- Section 5: Version History
Introduction
Promise Puppeteer is a drop-in test solution for handling ES-Next and Promise/A+ promises in your code under test. The goal of Promise Puppeteer is to make it as smooth and easy as possible to test code consuming promises without having to do a bunch of test gymnastics.
Why use Promise Puppeteer:
- Easy to use -- API is exposed to developer to allow for full control over promise execution
- Predictable -- Executes promise code as it behaves in the wild, making it easier to verify everything works as expected
- Deterministic execution -- Your test is separated from the world: resolve or reject from within tests
- Clear communication -- Built to fail when code acts unpredictably: Resolve and reject throw when called twice; Optionally throws an error if no catch or onFailure behavior is registered (default: on)
- Easy execution analysis -- Optional step-by-step execution of resolve behavior for easier analysis
Compatibility:
- ES-Next Promise Standard:
- Promise
- all
- race
- new Promise()
- Thenable
- then
- catch
- finally
- Promise
- Promise/A+
- then supports both onSuccess and onFailure optionally
Promise Puppeteer works both in Node and client-side code, so it integrates seamlessly into all of your test scenarios. With its clear, simple API, it is easy to either execute through the entire code stack or perform step-by-step evaluation of promise resolution.
Setup
Setup is as simple as performing an NPM installation and including the library in your test environment:
npm install promise-puppeteer --save-dev
The library exists at the following path:
project-root/node_modules/promise-puppeteer/index.js
That's it!
Test Examples
A common test example
A common test setup scenario would look like the following (using the Mocha test framework):
const sinon = ; const promiseDoubleFactory = ;const moduleUnderTestFactory = ; ;
A running thenable fake
An example of consuming a Promise Puppeteer thenable straight from the actual test suite is as follows:
const thenableFake = ; const thenStub = sinon; thenableFake ; assert;
It's worth noting thenableFake
adheres to the ES-Next promise standard, with the addition of resolve,
which will execute the promise as if it were resolved from an async executor (action).
Step-wise then resolution
You can step through a promise resolution with the resolveNext
function. The following execution allows the user to analyze what happens as each then executes and exits.
const thenableFake = ; const thenStub = sinon; thenableFake ; const result1 = thenableFake; // runs the first 'then'const result2 = thenableFake; // runs the second 'then'const result3 = thenableFake; // runs the third 'then' assert;assert;
Rejecting a thenable fake
Rejecting a thenable fake will work exactly as expected, executing no then onSuccess functions, jumping straight to the catch.
const thenableFake = ; const thenStub = sinon;const catchStub = sinon; thenableFake ; assert;assert;
PromiseFake and Thenable APIs
PromiseFake API
// Getting a new instantiable PromiseFake -- required for test state safetyconst PromiseFake = promiseDoubleFactory; // Promise.allconst thenableFake = PromiseFakeall /* these promises are not processed. */ ; // Promise.raceconst thenableFake = PromiseFake; // Instantiationconst thenableProxyFake = { // Code goes here // Resolving and rejecting DOES NOT initiate actual promise resolution}; // Available methods on thenableProxyFake:thenableProxyFake;thenableProxyFake;thenableProxyFake;thenableProxyFake; // Access to internal values:const resolveArguments = thenableProxyFakeresolveargs;const rejectArguments = thenableProxyFakerejectargs;
Thenable Fake API
// Getting a new thenable fake objectconst thenableFake = promiseDoubleFactory; // Chaining thens, catches and finallys:thenableFake ; // Turning off errors when catch is missing on a thenable fakethenableFake; // Resolve and execute onSuccess and onComplete functions completely:thenableFake; // Reject and execute onFailure and onComplete functions completely:thenableFake;
Special Case and Analysis Step-wise Resolution
// Verify resolveNext can be called safely:thenableFake; // Resolve onSuccess functions incrementally, calling onComplete functions upon last onSuccess execution completion:const outcome = thenableFake; // Returns outcome from internal execution
Version History
v1.0.0
Initial release:
- PromiseFake
- all
- race
- ThenableFake
- then
- catch
- finally
- resolve
- resolveNext
- reject