pact-gen-ts

# Pact-gen-ts Pact-gen-ts is a tool for generating contracts using TypeScript type definitions and custom JSDoc tags. It's an alternative to the [pact-js](https://github.com/pact-foundation/pact-js) package but without the necessity for writing separate tests. It provides automated, low maintenance and more flexible way to generate contracts according to [Pact specification version 2](https://github.com/pact-foundation/pact-specification). ## Installation and usage You can install pact-gen-ts using npm: ```bash npm install pact-gen-ts --save-dev ``` or yarn: ```bash yarn add --dev pact-gen-ts ``` Next you should create a minimal `pacts.config.js` or `pacts.config.cjs` configuration file in the root directory: ```js module.exports = { consumer: 'consumer-name', providers: [ { provider: 'some-provider', files: ['src/api/**/*.ts'], }, ], }; ``` where `files` property will be an array of glob patterns pointing to API functions definitions. After that pact-gen-ts is ready, now you need to mark all API functions which will be analysed: ```ts /** * @pact */ function fetchComments() { // ... } ``` The last thing is to execute the command: ```bash pact-gen-ts ``` which does the analysis and generates pacts in JSON format inside (by default) `./pacts` directory. ## Compatibility with TypeScript Due to TypeScript's occasional changes to its compiler API and not following semantic versioning in their releases, the latest versions of pact-gen-ts can only guarantee compatibility with the latest versions of TypeScript. If you're limited to historical versions of TypeScript, you should install a corresponding version of pact-gen-ts. The below table presents what TS versions pact-gen-ts will work with: | pact-gen-ts | TypeScript | | --------------- | ---------- | | 0.8 | 4.1 - 4.2 | | 0.9 - 0.9.3 | 4.5 - 4.6 | | 0.9.4 - 0.10.0 | 4.7 - 4.8 | | 0.11.0 | 4.9 | | 0.12.0 | 5.0 | | 0.13.0 | 5.1 | | 0.14.0 | 5.2 - 5.3 | | 0.15.0 | 5.4 | | 0.16.0 | 5.5 - 5.6 | | 0.17.0 - 0.19.0 | \>=5.7 | ## Configuration Pact-gen-ts uses configuration stored in `pacts.config.js` file in project's root directory: ```js module.exports = { consumer: 'consumer-name', buildDir: 'pacts', verbose: true, providers: [ { provider: 'provider-name', files: ['src/api/firstProvider/*.ts'], queryArrayFormat: 'indices', requestHeaders: { authorization: 'auth', }, responseHeaders: { 'Content-Type': 'application/json', }, }, ], }; ``` ### Options | Option | Required | Default | Description | | ------------------------------ | :------: | :----------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `consumer` | Yes | - | Consumer's name | | `providers[].provider` | Yes | - | Provider's name | | `providers[].files` | Yes | - | Array of glob patterns where API functions are defined | | `providers[].requestHeaders` | No | - | Request headers shared across all requests | | `providers[].responseHeaders` | No | - | Response headers shared across all responses | | `providers[].queryArrayFormat` | No | `"brackets"` | Sets separator for array in query - possible options are `"indices"`, `"brackets"`, `"comma"` and `"repeat"` [(source)](https://github.com/ljharb/qs#stringifying). The default value is `brackets`. | | `buildDir` | No | `./pacts` | Directory where generated pacts will be placed | | `verbose` | No | `false` | If set to `true` additional information during pacts generating process will be logged | You can specify common config shared between providers in **pacts.config.js**: ```js module.exports = { commonConfigForProviders: { queryArrayFormat: 'indices', requestHeaders: { authorization: 'auth', }, responseHeaders: { 'Content-Type': 'application/json', }, }, providers: [ { provider: 'first-provider', files: ['src/api1/**/*.ts'], }, { provider: 'second-provider', files: ['src/api2/**/*.ts'], }, { provider: 'third-provider', files: ['src/api3/**/*.ts'], // you can override common config in provider config queryArrayFormat: 'comma', }, ], }; ``` ## Integrations #### Axios - `@pact-axios` Sets REST method, expected body for the current response, expected body for current request and query based on axios definitions. ```ts /** * @pact * @pact-axios * @pact-path /api */ async function fetchComments(commentId: string) { const {data} = await axios.post<string>('/api', {commentId}); // ... } ``` **IMPORTANT** - If axios function does not return any type explicitly it is needed to set `<void>` as an axios return type ```ts /** * @pact * @pact-axios * @pact-path /api */ async function fetchComments(commentId: string) { await axios.post<void>('/api', {commentId}); } ``` ## Pact interaction options These JSDoc custom tags are used to adjust generated pact interactions. #### `@pact-method` Sets REST method (GET, POST, PUT, PATCH, DELETE etc.). ```ts /** * @pact * @pact-method GET */ function fetchComments() { // ... } ``` #### `@pact-path` Sets path. ```ts /** * @pact * @pact-path /api/images/100 */ function fetchImage(imageId: number) { // ... } ``` #### `@pact-description` Sets description, if not provided, description is set using name of the function / variable / property. ```ts /** * @pact * @pact-description "request to get comments" */ function fetchComments() { // ... } ``` #### `@pact-response-status` Sets response status, if not provided, it is set based on given HTTP method. ```ts /** * @pact * @pact-response-status 200 */ function fetchComments() { // ... } ``` #### `@pact-request-header` Adds a header to the current request, can override option defined in `pacts.config.js`. ```ts /** * @pact * @pact-request-header "Content-Type" "application/pdf" */ function fetchImage(imageId: number) { // ... } ``` #### `@pact-response-header` Adds a header to the current response, can override option defined in `pacts.config.js`. ```ts /** * @pact * @pact-response-header "Content-Type" "application/pdf" */ function fetchImage(imageId: number) { // ... } ``` #### `@pact-response-body` Sets expected body for the current response. ```ts /** * @pact */ async function fetchComments() { // ... const response = await axios.get<string>('/api'); /** @pact-response-body */ const data = response.data; // ... } ``` **IMPORTANT** - JSDoc has to be applied to separate variable - **not** directly to axios response ```ts async function fetchComments() { // ... /** @pact-response-body */ -WRONG!; const response = await axios.get<string>('/api'); /** @pact-response-body */ -CORRECT; const data = response.data; // ... } ``` #### `@pact-request-body` Sets expected body for current request. ```ts function addComment(/** @pact-request-body */ newComment: NewComment) { // ... } interface NewComment { content: string; postId: string; } ``` or ```js function addComment(postId: string, commentContent: string) { /** @pact-request-body */ const newComment = { postId, commentContent, }; // ... } ``` #### `@pact-query` Sets query, **IMPORTANT** - JSDoc tag has to be applied to an object - not a primitive value. Array separator format can be set using `queryArrayFormat` in providers options. ```ts function fetchComments(/** @pact-query */ query: Query) { // ... } interface Query { fromUser: string; postId: string; } ``` or ```ts function fetchComments(pageNo: string) { /** @pact-query */ const params = { pageNo, }; // ... } ``` ### Pact matchers Typescript types can describe the shape of the data and define possible values a variable can store. Pacts definition require specific values, that's why for some individual cases additional information needs to be added. For example a type `string` without any modifications will be replaced with simple `text` which can be later matched by type. Sometimes that's not enough - the matcher needs to be more specific, for instance instead of simple `text` we need a string in a particular format like `name@example.com` - that's where a `@pact-matcher` tag is used. Pact-matchers are used in the type/interface definition: ```ts interface CommentDTO { id: number; /** @pact-matcher email */ user: string; } ``` Provided common matchers: | Pact matcher | Result | | ----------------------------------------------- | ----------------------------------- | | `/** @pact-matcher email */` | email@example.com | | `/** @pact-matcher iso-date */` | 2021-04-13 | | `/** @pact-matcher iso-datetime */` | 2021-04-13T10:14:53+01:00 | | `/** @pact-matcher iso-datetime-with-millis */` | 2021-04-13T10:14:53.123+01:00 | | `/** @pact-matcher iso-time */` | T10.14.53.342Z | | `/** @pact-matcher timestamp */` | Tue, 13 Apr 2021 10:14:53 -0400 | | `/** @pact-matcher uuid */` | ce11b6e-d8e1-11e7-9296-cec278b6b50a | | `/** @pact-matcher ipv4 */` | 127.0.0.13 | | `/** @pact-matcher ipv6 */` | ::ffff:192.0.2.128 | | `/** @pact-matcher hex */` | A4C3Ff | If that's not enough you can easily provide own value using `/** @pact-example */`: ```ts interface Address { city: string; address: string; /** @pact-example 99-400 */ postCode: string; /** @pact-example 45 */ age: number; } ```