docs: Added example with TypeScript, Jest and Fetch

[justsml]

The PR adds an example using TypeScript, Jest, and Fetch.

It features a handy utility method (autoSetupPolly()) I've refined across my last 2 integrations of this tool:

// `utils/auto-setup-polly.ts`
import path from 'path';
import { setupPolly } from 'setup-polly-jest';
import { Polly } from '@pollyjs/core';
import NodeHttpAdapter from '@pollyjs/adapter-node-http';
import FSPersister from '@pollyjs/persister-fs';

Polly.register(NodeHttpAdapter);
Polly.register(FSPersister);

const mode = process.env.POLLY_MODE === 'record' ? 'record' : 'replay';

export default function autoSetupPolly() {
  // TODO: Customize PollyJS' config for your project!
  return setupPolly({
    adapters: ['node-http'],
    mode,
    recordFailedRequests: true,
    recordIfMissing: true,
    persister: 'fs',
    persisterOptions: { fs: { recordingsDir: path.resolve(__dirname, '../../__recordings__') } },
  });
}

To use in test files

Add this one-liner near the top of your test script:

autoSetupPolly(); 

For more complex use cases you can store a reference to the returned context:

let pollyContext = autoSetupPolly();

Key files

• examples/typescript-jest-node-fetch/src/

  • utils/auto-setup-polly.ts
  • github-api.ts
  • github-api.test.ts

• I have added tests to cover my changes.

• My change requires a change to the documentation.

• I have updated the documentation accordingly.

• My code follows the code style of this project.

• My commits and the title of this PR follow the Conventional Commits Specification.

• I have read the contributing guidelines.

[offirgolan]

Thanks for the PR @justsml! Left a few minor comments but other than that lgtm.

[justsml]

Hi @offirgolan , hope you're doing well!

Please let me know if you are waiting on me for anything; I believe I've included all your suggestions. 🤘

Thanks in advance for your time!

[mcmire]

I'm testing this library in our test suite. My feeling is that Polly should be as automatic as possible and devs shouldn't have to think about it (unless they want to mock a request). I found that I could set up Polly without having to add anything manually to tests using this:

// tests/setupTestsAfterEnv.ts

import path from 'path';
import { setupPolly } from 'setup-polly-jest';
import NodeHttpAdapter from '@pollyjs/adapter-node-http';
import FSPersister from '@pollyjs/persister-fs';

global.pollyContext = setupPolly({
  adapters: [NodeHttpAdapter],
  persister: FSPersister,
  persisterOptions: {
    fs: {
      recordingsDir: path.resolve(__dirname, '__recordings__'),
    },
  },
  // logLevel: 'info',
  recordIfMissing: false,
  recordFailedRequests: true,
  expiresIn: '30d',
});

// tests/global.d.ts
// note that you will have to include this in your tsconfig.json somehow (automatically or manually)

import { setupPolly } from 'setup-polly-jest';

declare global {
  /* eslint-disable-next-line @typescript-eslint/no-namespace */
  namespace NodeJS {
    interface Global {
      pollyContext: ReturnType<typeof setupPolly>;
    }
  }
}

// jest.config.js
module.exports = {
  // ...
  setupFilesAfterEnv: ['./tests/setupTestsAfterEnv.ts'],
  // ...
}

This way pollyContext is magically available in any test.

Obviously this is a little bit specific, but what do you think about this approach?

[justsml]

I love where you're going @mcmire - I think Polly is 🔥 when it's transparent, so your code doesn't change depending on if you want to mock or not.

I was going to include something similar to this pattern! The reason I didn't is because I think an opt-in design can meet more use cases.
As it still allows you to wire it up in setupFilesAfterEnv scripts:

// `./tests/setupFilesAfterEnv.ts`
import { autoSetupPolly } from './src/utils/auto-setup-polly';

declare global {
  namespace NodeJS {
    interface Global {
      pollyContext: ReturnType<typeof autoSetupPolly>;
    }
  }
}

global.pollyContext = autoSetupPolly();

export default global.pollyContext;

Maybe another example or some comments in the README is warranted?

[mcmire]

Ah yeah that's a fair point. This technique is also useful if you're slowly introducing Polly into a test suite, I'd imagine. In that case, an extra example would be nice, but not necessary.

[offirgolan]

Hi @justsml, this looks good to me! Let me know if this is ready to be merged

[justsml]

Hi @offirgolan
This is good to merge!