{"id":17148431,"url":"https://github.com/aholstenson/dumbfound","last_synced_at":"2025-04-13T11:40:57.366Z","repository":{"id":55854399,"uuid":"120959492","full_name":"aholstenson/dumbfound","owner":"aholstenson","description":"Randomized testing for JavaScript and TypeScript","archived":false,"fork":false,"pushed_at":"2020-12-11T06:49:03.000Z","size":905,"stargazers_count":8,"open_issues_count":15,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T02:43:48.943Z","etag":null,"topics":["randomized-testing","testing"],"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/aholstenson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-09T21:50:43.000Z","updated_at":"2023-06-27T05:29:12.000Z","dependencies_parsed_at":"2022-08-15T07:51:08.605Z","dependency_job_id":null,"html_url":"https://github.com/aholstenson/dumbfound","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aholstenson%2Fdumbfound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aholstenson%2Fdumbfound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aholstenson%2Fdumbfound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aholstenson%2Fdumbfound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aholstenson","download_url":"https://codeload.github.com/aholstenson/dumbfound/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248709373,"owners_count":21149178,"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":["randomized-testing","testing"],"created_at":"2024-10-14T21:28:33.617Z","updated_at":"2025-04-13T11:40:57.327Z","avatar_url":"https://github.com/aholstenson.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dumbfound\n\nRandomized testing for JavaScript and TypeScript. Dumbfound hooks into test\nrunners such as [Mocha](https://mochajs.org/) and [Jest](https://jestjs.io/)\nand provides randomization for specified tests and helps with making test\nfailures reproducible.\n\n## Introduction\n\nRandomized testing is built around the idea that tests should sometimes fail,\nand that every time a test fails it helps improve the quality of your project.\nRandomized testing helps with failure by introducing limited randomness into\ntest cases to help find edge cases.\n\nDumbfound is built around supplying deterministic randomness that can be used\nby a test case to generate random data. The deterministic aspect helps with\nmaking test failures reproducible by providing a seed that can be used to\nreplay the test case.\n\nRunners are currently available for [Jest][jest] and [Mocha][mocha].\n\n## Example using Jest\n\nInstall `dumbfound-jest` into your local project:\n\n```\nnpm install --save-dev dumbfound-jest\n```\n\nUse it in your tests:\n\n```javascript\nconst { randomizedTest, randomizedRuns } = require('dumbfound-jest');\n\nrandomizedTest('Example', random =\u003e {\n  const totalOrders = random.intBetween(5, 10);\n\n  // Do something useful with the test here\n});\n\n// Generate a random number of runs of the given test\nrandomizedRuns('Group name', 1, 5, () =\u003e {\n  randomizedTest('Test in group', random =\u003e {\n    ...\n  });\n});\n```\n\n## Randomizer and generators\n\nThe randomizer is the main API for generating random values. For most test\nrunners it is supplied as the first argument in the test function. Methods on\nthe object can be used to generate random values by invoking them either\ndirectly or via a generator function.\n\nExample invoking them directly:\n\n```javascript\n// Generate an int between 0 and 500\nconst i = random.int(500);\n\n// Pick an item\nconst picked = random.pick([ 'a', 'b', 'c' ]);\n```\n\nGenerators are functions that resolve a value when invoked. The Randomizer API\nis available in a generator form, via the `gen` property. Generators\nare useful to model a more complex data that you want to use several times.\n\nExample of creating generator functions:\n\n```javascript\n// Create a function that generates an int between 0 and 500\nconst intCreator = random.gen.int(500);\n\n// Generate an int between 0 and 500\nconst i = intCreator();\nconst i2 = intCreator(); // Will generate another int\n\n// Create a picker function\nconst picker = random.gen.pick([ 'a', 'b', 'c' ]);\n// Pick the item\nconst picked = picker();\n```\n\nExample of more complex generator:\n\n```javascript\n/*\n * Create a generator that produces an array between 5 and 25 items with\n * ASCII strings.\n */\nconst fn = random.gen.array(\n  random.gen.intBetween(5, 25),\n  random.gen.ascii()\n);\n\nconst array1 = fn();\nconst array2 = fn();\n```\n\n## Randomizer and Generator API\n\nFor randomizer these methods will return the generated value and for generators\nthey will return a function that can be used to generate a value within the\nchosen bounds.\n\n### Numbers\n\n* `number(max?: number): number` - generate a number between `-9007199254.740992`\n  and `9007199254.740992`. If max is specified generate a number between `0` and\n  max (inclusive).\n* `numberBetween(min: number, max: number): number` - generate a number between\n  min (inclusive) and max (inclusive).\n* `int(max?: number): number` - generate a whole number between `-9007199254740991`\n  and `9007199254740991`. If max is specified generate a whole number between `0`\n  and max (inclusive).\n* `intBetween(min: number, max: number): number` - generate a whole number between \n  min (inclusive) and max (inclusive).\n* `evilNumber(max?: number): number` - generate an evil number that will bias\n  towards numbers that can cause issues. Follows the same rules as `number(max?)`.\n* `evilNumberBetween(min: number, max: number): number` - generate an evil\n  number in the given range that will bias towards numbers that can cause \n  issues.\n\n### Booleans\n\n* `boolean(trueProbability=0.5): boolean` - generate either `true` or `false`.\n  Optionally specify a probability to return true between 0 and 1.\n* `frequently(): boolean` - generate `true` frequently and `false` otherwise.\n* `rarely(): boolean` - generate `false` frequently and `true` otherwise.\n\n### Strings\n\nAll string generation supports the optional `length` parameter, if not specified\na string between 0 and 20 characters will be returned.\n\n* `string(generator: CharGenerator | CharGenerator[], length?: number): string` - \n  generate a string using the given character generator.\n* `asciiDigits(length?: number): string` - generate string with ASCII digits\n  (0 to 9) of the given length.\n* `asciiLowercase(length?: number): string` - generate string with ASCII\n  lower-case characters (a to z) of the given length.\n* `asciiUppercase(length?: number): string` - generate string with ASCII\n  upper-case characters (A to Z) of the given length.\n* `ascii(length?: number): string` - generate string with ASCII characters \n  (lower-case, upper-case, digits) of the given length.\n* `asciiWithSpaces(length?: number): string` - generate string with ASCII\n  characters including spaces of the given length.\n* `unicode(length?: number): string` - generate a string with any Unicode\n  character of the given length.\n\nThere are a lot of character sources available:\n\n```javascript\nconst { asciiDigits, unicodeBasicLatin, unicodeArrows } = require('dumbfound-testRunnerHere');\n\n// Generate with a single character source\nrandomizer.string(asciiDigits, 40);\n\n// Generate with multiple character sources\nrandomizer.string([ unicodeBasicLatin, unicodeArrows ], 40);\n```\n\nSee [available sources](https://github.com/aholstenson/dumbfound/tree/master/docs/character-generators.md)\nfor a list of character sources.\n\n### Arrays and Sets\n\nArrays can be created via the `array` function and require a generator function.\n\n```javascript\n// Generate an array with 25 random numbers\nconst arr1 = random.array(25, random.gen.int(500000));\n\n// Generate an array with 10 strings consisting of ASCII digits\nconst arr2 = random.array(10, randomizer =\u003e randomizer.asciiDigits());\n\n// Generate an array of primitive values between 5 and 10 items\nconst arr3 = random.array(random.intBetween(5, 10), random.gen.primitiveValue());\n```\n\n* `array(length: number, generator: Generator\u003cValueType\u003e): ValueType[]` - \n  generate an array of the given length, the generator should be a function that\n  returns a single value.\n* `uniqueArray(length: number, generator: Generator\u003cValueType\u003e): ValueType[]` -\n  generate an array with unique items of the given length. Generator should be\n  a function that returns a single value.\n* `set(length: number, generator: Generator\u003cValueType\u003e): Set\u003cValueType\u003e` - \n  generate a Set (with unique items) of the given length.\n\n### Static values\n\n* `nan(): NaN` - always generate a `NaN` value. For use as a generator.\n* `null(): null` - always generate a `null` value. For use as a generator.\n* `undefined(): undefined` - always generate a `undefined` value. For use as a generator.\n\n### Value picking\n\n* `pick(items: ValueType[]): ValueType` - pick a single item from the given\n  array. Items in the array may be generators in which case they will be resolved.\n* `pick(items: ValueType[], weights: number[]): ValueType` - pick a single item\n  from the given array while applying weights to each item.\n* `primitiveValue()` - generate a primitive value, either `null`, `NaN`,\n  `undefined`, a number, a boolean or a string. \n* `truthy(): any` - generate a truthy value, that is a value that when used with \n  `if(value)` would resolve to `true`.\n* `falsy(): any` - generate a falsy value, that is a value that when used with\n  `if(value)` would resolve to `false`.\n\n### Misc\n\n* `uuid(): string` - generate a UUIDv4.\n* `get(generator: Generator\u003cValueType\u003e): ValueType` - resolve by invoking a\n  generator function. The function may take a randomizer as its first argument\n  and should return a value.\n\n## A note on randomness\n\nThe randomness provided by this library is not cryptographically secure, and\nthe quality of the random generator is \"good enough\" for testing. Don't use it\nfor things that need statistically provable randomness.\n\n[jest]: https://github.com/aholstenson/dumbfound/tree/master/packages/jest\n[mocha]:https://github.com/aholstenson/dumbfound/tree/master/packages/mocha\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faholstenson%2Fdumbfound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faholstenson%2Fdumbfound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faholstenson%2Fdumbfound/lists"}