{"id":15747207,"url":"https://github.com/rwaskiewicz/factory-mate","last_synced_at":"2025-03-31T06:26:55.211Z","repository":{"id":57232394,"uuid":"96705665","full_name":"rwaskiewicz/factory-mate","owner":"rwaskiewicz","description":"A TypeScript library for creating domain objects during testing","archived":false,"fork":false,"pushed_at":"2017-12-31T19:47:16.000Z","size":35,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-03-26T23:03:40.431Z","etag":null,"topics":["factory","testing","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rwaskiewicz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.MD","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-09T19:13:22.000Z","updated_at":"2019-09-18T21:27:48.000Z","dependencies_parsed_at":"2022-08-31T20:51:01.646Z","dependency_job_id":null,"html_url":"https://github.com/rwaskiewicz/factory-mate","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwaskiewicz%2Ffactory-mate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwaskiewicz%2Ffactory-mate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwaskiewicz%2Ffactory-mate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwaskiewicz%2Ffactory-mate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rwaskiewicz","download_url":"https://codeload.github.com/rwaskiewicz/factory-mate/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246425927,"owners_count":20775235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["factory","testing","typescript"],"created_at":"2024-10-04T05:03:55.171Z","updated_at":"2025-03-31T06:26:55.185Z","avatar_url":"https://github.com/rwaskiewicz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FactoryMate\n[![Build Status](https://travis-ci.org/rwaskiewicz/factory-mate.svg?branch=develop)](https://travis-ci.org/rwaskiewicz/factory-mate)\n[![npm version](https://badge.fury.io/js/factory-mate.svg)](https://badge.fury.io/js/factory-mate)\n[![Coverage Status](https://coveralls.io/repos/github/rwaskiewicz/factory-mate/badge.svg?branch=develop)](https://coveralls.io/github/rwaskiewicz/factory-mate?branch=develop)\n\nFactoryMate is a TypeScript-based fixture library for instantiating domain objects for testing purposes, inspired by \nthe [Factory Duke](https://github.com/regis-leray/factory_duke) project.\n\n\n## Table of Contents\n- **[Getting Started](#getting-started)**\u003cbr\u003e\n- **[Example Project](#example-project)**\u003cbr\u003e\n- **[Usage](#usage)**\u003cbr\u003e\n  - **[Factory Classes](#factory-classes)**\u003cbr\u003e\n  - **[Additional Building Methods](#additional-building-methods)**\u003cbr\u003e\n    - **[Named Templates](#named-templates)**\u003cbr\u003e\n    - **[Overriding a Template's Variables](#overriding-a-templates-variables)**\u003cbr\u003e\n    - **[Building Many of the Same Object](#building-many-of-the-same-object)**\u003cbr\u003e\n- **[Sequence Generation](#sequence-generation)**\u003cbr\u003e\n  - **[NumberGenerator](#numbergenerator)**\u003cbr\u003e\n  - **[ProvidedValueGenerator](#providedvaluegenerator)**\u003cbr\u003e\n- **[Recipes](#recipes)**\u003cbr\u003e\n  - **[Creating a Random Number Generator](#creating-a-random-number-generator)**\u003cbr\u003e\n- **[License](#license)**\u003cbr\u003e\n\n## Getting Started\n\nFactoryMate can be installed via NPM:\n```\nnpm install --save-dev factory-mate\n```\n\n## Example Project\nAn example project using FactoryMate can be found here: [FactoryMateConsumer](https://github.com/rwaskiewicz/factory-mate-consumer)\n\n## Usage\n\nGiven a simple domain object:\n\n``` typescript\n// GroceryItem.ts\nexport class GroceryItem {\n    public groceryName = '';\n}\n```\nA factory can be registered using `FactoryMate.define()`:\n\n``` typescript\nimport { FactoryMate } from 'factory-mate';\nimport { GroceryItem } from './GroceryItem';\n\nFactoryMate.define(GroceryItem, (): GroceryItem =\u003e {\n    const groceryItem = new GroceryItem();\n    groceryItem.groceryName = 'crispy chips';\n    return groceryItem;\n});\n```\n\n`FactoryMate.define()` takes two arguments:\n1. The class being registered \n2. An initialization function - a function that returns the 'template' of the object. \n\nEvery time FactoryMate is used to create an instance of the registered object, that instance's properties will have the same values as those defined in template. To build an instance of a registered class:\n\n``` typescript\nconst groceryItem: GroceryItem = FactoryMate.build(GroceryItem.name);\n\nconsole.log(JSON.stringify(groceryItem)); // '{\"groceryName\":\"crispy chips\"}'\n```\n\n### Factory Classes\nIt is recommended that a factory class be created for each domain object.  Factory classes can  be created by annotating the new class with `@FactoryMateAware` and calling the static `FactoryMate.define()` method in that class:\n``` typescript\n// GroceryItemFactory.ts\nimport { FactoryMate, FactoryMateAware } from 'factory-mate';\nimport { GroceryItem } from './GroceryItem';\n\n@FactoryMateAware\nexport class GroceryItemFactory {\n    // The @FactoryMateAware annotation will automatically call the define() function at runtime\n    public define() { \n        FactoryMate.define(GroceryItem, (): GroceryItem =\u003e {\n            const groceryItem = new GroceryItem();\n            groceryItem.groceryName = 'crispy chips';\n            return groceryItem;\n        });\n    }\n}\n```\n\n### Additional Building Methods\n#### Named Templates\nIn certain cases, it may be desirable to have more than one template per class.  In order to create more than one template per class, or to give a template a name other than the class it is representing, a 'named template' can be created using ```defineWithName```:\n\n``` typescript\n// GroceryItemFactory.ts\nimport { FactoryMate, FactoryMateAware } from 'factory-mate';\nimport { GroceryItem } from './GroceryItem';\n\n@FactoryMateAware\nexport class GroceryItemFactory {\n    // The @FactoryMateAware annotation will automatically call the define() function at runtime\n    public define() { \n        FactoryMate.define(GroceryItem, (): GroceryItem =\u003e {\n            const groceryItem = new GroceryItem();\n            groceryItem.groceryName = 'crispy chips';\n            return groceryItem;\n        });\n\n        FactoryMate.defineWithName(GroceryItem, 'specialChips', (): GroceryItem =\u003e {\n            const groceryItem = new GroceryItem();\n            groceryItem.groceryName = 'limited edition flavor chips';\n            return groceryItem;\n        });\n    }\n}\n```\n\n#### Overriding a Template's Variables\nIf for specific tests there is a need to override one or more variables in the template, this can be accomplished via an optional parameter to `build`:\n\n``` typescript\nconst groceryItem: GroceryItem = FactoryMate.build(GroceryItem.name,\n      (u: GroceryItem) =\u003e {\n        u.groceryName = 'chunky cookies';\n      });\n```\n\n#### Building Many of the Same Object\nTo build several objects of the same type:\n``` typescript\nconst groceryItems: GroceryItem[] = FactoryMate.buildMany(GroceryItem.name, 3);\n```\n\n## Sequence Generation\n### NumberGenerator\nFactoryMate supports infinite, numerical sequence generation via the ```NumberGenerator``` class.  This can be helpful for the purposes of generating ID values for domain objects to better represent real world scenarios (e.g. IDs in a data store) \n\nIn order to add sequential generation support to an entity, it can be imported into it's factory as such:\n``` typescript\nimport { FactoryMate, FactoryMateAware } from 'factory-mate';\nimport { NumberGenerator } from 'factory-mate';\nimport { GroceryItem } from './GroceryItem';\n\n@FactoryMateAware\nexport class GroceryItemFactory {\n    public define() {\n        // Defines the NumberGenerator instance to be used across all calls to FactoryMate.build(GroceryItem.name);\n        const numberGenerator = new NumberGenerator();\n\n        FactoryMate.define(GroceryItem, (): GroceryItem =\u003e {\n            const groceryItem = new GroceryItem();\n            // The nextValue() method retrieves the next value in the sequence\n            groceryItem.id = numberGenerator.nextValue();\n            groceryItem.groceryName = 'chewy cookies';\n            return groceryItem;\n        });\n    }\n}\n```\nUsing the factory method above, three sequential calls to ```FactoryMate.build(GroceryItem.name)``` will result in the following:\n\n``` typescript\nconst groceryItem1: GroceryItem = FactoryMate.build(GroceryItem.name);\nconst groceryItem2: GroceryItem = FactoryMate.build(GroceryItem.name);\nconst groceryItem3: GroceryItem = FactoryMate.build(GroceryItem.name);\n\nconsole.log(JSON.stringify(groceryItem1)); //'{\"id\":1,\"groceryName\":\"chewy cookies\"}'\nconsole.log(JSON.stringify(groceryItem2)); //'{\"id\":2,\"groceryName\":\"chewy cookies\"}'\nconsole.log(JSON.stringify(groceryItem3)); //'{\"id\":3,\"groceryName\":\"chewy cookies\"}'\n```\n#### Changing Numerical Sequence Values\nBy default, ```NumberGenerator``` starts at a value of 1 and increments by 1.  These values can be altered at instantiation time if desired\n``` typescript\n// Start at one, increment by one: 1, 2, 3 ...\nconst numberGenerator = new NumberGenerator();\n// Start at one, increment by two: 1, 3, 5 ...\nconst numberGenerator = new NumberGenerator(1, 2);\n// Start at zero, increment by one: 0, 1, 2, ...\nconst numberGenerator = new NumberGenerator(0);\n```\n\n### ProvidedValueGenerator\n\nFactoryMate also supports sequence generation by means of the `ProvidedValueGenerator` class. `ProvidedValueGenerator` is capable of returning values from an `Array` of numbers, strings, objects, etc. that was provided to the class upon instantiation:\n\n``` typescript\nconst providedValueGenerator = new ProvidedValueGenerator(['up', 'left', 'right']);\nconst firstValue = providedValueGenerator.nextValue();  // 'up'\nconst secondValue = providedValueGenerator.nextValue(); // 'left'\nconst thirdValue = providedValueGenerator.nextValue();  // 'right'\nconst fourthValue = providedValueGenerator.nextValue(); // Error: 'Out of bounds!'\n```\n\nBy default, `ProvidedValueGenerator` supports finite-sequence generation.  In order to create an infinite-sequence generator, set the `continuousMode` flag to `true` as a part of the class's instantiation:\n``` typescript\nconst providedValueGenerator = new ProvidedValueGenerator(['up', 'left', 'right'], true);\nconst firstValue = providedValueGenerator.nextValue();  // 'up'\nconst secondValue = providedValueGenerator.nextValue(); // 'left'\nconst thirdValue = providedValueGenerator.nextValue();  // 'right'\nconst fourthValue = providedValueGenerator.nextValue(); // 'up'\nconst fifthValue = providedValueGenerator.nextValue(); // 'left'\nconst sixthValue = providedValueGenerator.nextValue();  // 'right'\n...\n```\n\n## Recipes \n### Creating a Random Number Generator\nA random number generator can be created by passing a `Math.random()` function call wrapped in an array to the `ProvidedNumberGenerator` class:\n\n```typescript\n// Each call to randomNumberGenerator.nextValue() will produce a number between 0 and 9\nconst randomNumberGenerator = new ProvidedValueGenerator([Math.floor(Math.random() * 10)], true);\n\nFactoryMate.define(GroceryItem, (): GroceryItem =\u003e {\n  const groceryItem = new GroceryItem();\n  groceryItem.id = randomNumberGenerator.nextValue();\n  groceryItem.groceryName = 'Chips';\n  return groceryItem;\n});\n```\n\n## License\nFactoryMate is distributed under the [MIT license](https://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frwaskiewicz%2Ffactory-mate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frwaskiewicz%2Ffactory-mate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frwaskiewicz%2Ffactory-mate/lists"}