Array

Generate array values.

tuple

Generate tuples - or more precisely arrays - by aggregating the values generated by its underlying arbitraries.

Signatures:

• fc.tuple(...arbitraries)

with:

• ...arbitraries — arbitraries that should be used to generate the values of our tuple

Usages:

fc.tuple(fc.nat());
// Examples of generated values: [15], [1564085383], [2147483642], [1564562962], [891386821]…

fc.tuple(fc.nat(), fc.string());
// Examples of generated values: [17,"n"], [1187149108,"{}"], [302474255,"!!]"], [2147483618,"$#"], [21,"lv V!\""]…

Resources: API reference.
Available since 0.0.1.

array

Array of random length containing values generated by arb.

Signatures:

• fc.array(arb)
• fc.array(arb, {minLength?, maxLength?, size?, depthIdentifier?})

with:

• arb — arbitrary instance responsible to generate values
• minLength? — default: 0 — minimal length (included)
• maxLength? — default: 0x7fffffff more — maximal length (included)
• size? — default: undefined more — how large should the generated values be?
• depthIdentifier? — default: undefined — when specified, the array will impact the depth attached to the identifier to avoid going too deep if it already generated lots of items for current level

Usages:

fc.array(fc.nat());
// Examples of generated values:
// • [1811605556]
// • [773390791,2091685325,1242440672]
// • []
// • [1782327935,900193957,2005682058,1190044745,1361174456,1816521832]
// • [2039519833,1820186979,1716322482,1252099479,313246778,1462590114,1981305846,1755169295]
// • …

fc.array(fc.nat(), { minLength: 3 });
// Examples of generated values:
// • [30,1812443734,26]
// • [536894957,149319825,1808423364,1511394264]
// • [1265639866,1672446215,356045957,1686054822,2086860087]
// • [2147483618,2147483620,1209289481]
// • [946187936,1504050852,144134225,2105232789,194205091,171397027,437743867,328587192,403202026,943599425,272125438]
// • …

fc.array(fc.nat(), { maxLength: 3 });
// Examples of generated values: [], [536894957], [1265639866,1672446215], [2147483618,2147483620], [1396071052,413181514,728831399]…

fc.array(fc.nat(), { minLength: 5, maxLength: 7 });
// Examples of generated values:
// • [2013730136,353952753,1490777806,634915573,1978586276]
// • [11,2147483643,1549284389,2,2085769824,1046376312]
// • [131262217,28,2008543832,464574638,2147483621]
// • [29,1410245876,741880759,944485652,27]
// • [1558059373,1486409544,138880328,1775525007,1289633061]
// • …

fc.array(fc.nat(), { maxLength: 50, size: 'max' });
// Note: By specifying size to "max", we enforce the fact that we want generated values to have between
// 0 and 50 items. In other words, we want to use the full range of specified lengths.
// Note: If not defined, by default, the size is "=" except if there is a maxLength provided and the
// global setting defaultSizeToMaxWhenMaxSpecified explicitely set to true. In such case it will
// automatically be defaulted to "max".
// Examples of generated values:
// • [2013730136,353952753,1490777806,634915573,1978586276,205766418,1175483977,32404726,52946578,1069691063,626810743,719356509,1263272304,1824194201,1899370697,1015020872,1705828766,1764355915]
// • [11,2147483643,1549284389,2,2085769824]
// • [131262217,28,2008543832,464574638]
// • [29,1410245876,741880759,944485652,27,15]
// • [1558059373,1486409544,138880328,1775525007,1289633061,2110277820,2132428886,243113350,370748226,1289875763,1926931276,777271555,200391383,382812004,767046802,1658449850,471365442,258979782,1763577358,875799138,1041944829,769854926,874760332,442170309,91717126,113325162,88812665,1097842037,804561500,1870859458,853896552,50228752,492015973]
// • …

fc.array(fc.nat(), { maxLength: 100000, size: '+1' });
// Note: From a specification point of view, the algorithm is supposed to handle up to 100,000 items.
// But, even if I want to test the algorithm on large entries I don't want to spend hours in it (it may
// not scale linearly...). By setting size to "+1" I tell fast-check that I want values larger than usual
// ones (~10x factor). If I wanted even larger ones I could have used "+2" (~100x factor), "+3" (~1000x factor)
// or "+4" (~10000x factor). On the opposite, if I wanted smaller arrays I could have used "-1" (~10x smaller)...
// Note: Size could also have been set explicitely to "=" to say: "I want the size used by default no matter the
// specified maxLength". If not defined, by default, the size is "=" except if there is a maxLength provided
// and the global setting defaultSizeToMaxWhenMaxSpecified explicitely set to true. In such case it will
// automatically be defaulted to "max".
// Examples of generated values:
// • [1499459057,110432617,339543317,591661354,869690762,903936065,24,2147483618,18,1350034659]
// • [1850529194,1877982582,756109358,26,5,10,28,933512138,3,2147483647,143549967,151486834]
// • [186214456,1304129127,236610033,1770333983,677229078,1874153157,647904631,2015875422,839334870,46102013,1303893735,1699495931,10156178,336616013,2094724689,1925510000,1437440576,355042345,2143594345,1734467233,1593448698,574044973,1111310760,76274244,1956358794,1928061897,1318184432,782455007,1247892810,249565393,857651507,1873602460,57966219,752962298,880822188,823737098,280536251,79820007,677389259,1771811403,734630420,1012881515,314976648,466444542,72628732,941152314,390898317,957018849,235229362,2043578224,1280394640,658661493,1592383816,1940643736,832534240,1299579948,954930320,205824052,1320157423,1943789311,2145245274,456558002,1177939177,472568424,90595308,390737624,1775798785,1141982866,1634207099,216091479]
// • [754990229,2147483617,2020328162,8653370]
// • [956688959,1282167266,1451864941]
// • …

fc.letrec((tie) => ({
  self: fc.record({
    value: fc.nat(),
    children: fc.oneof(
      { depthSize: 'small', depthIdentifier: 'id:self' },
      fc.constant([]),
      fc.array(tie('self'), { depthIdentifier: 'id:self' }),
    ),
  }),
})).self;
// Note: We define a recursive tree structure with children defaulting to the empty array with an higher probability
// as we go deeper (thanks to `fc.oneof`) and also as we tend to generate lots of items (thanks to `depthIdentifier`
// passed to `fc.array` and being the same value as the one passed to `fc.oneof`).
// Note: For the moment, `fc.array` cannot stop the recursion alone and need to be combined with `fc.oneof` or any other
// helper being able to fallback to base cases with an higher probability as we go deeper in the recursion.
// Examples of generated values:
// • {"value":424778306,"children":[]}
// • {"value":27,"children":[{"value":314632820,"children":[]},{"value":494880843,"children":[]},{"value":241922623,"children":[]},{"value":1909847367,"children":[]},{"value":955571083,"children":[]},{"value":96082336,"children":[]},{"value":56407905,"children":[]},{"value":1286754465,"children":[]},{"value":188039153,"children":[]},{"value":853104761,"children":[]}]}
// • {"value":7,"children":[]}
// • {"value":2147483619,"children":[]}
// • {"value":15,"children":[{"value":1009275606,"children":[]},{"value":2147483630,"children":[{"value":1715614519,"children":[]}]}]}
// • …

Resources: API reference.
Available since 0.0.1.

uniqueArray

Array of random length containing unique values generated by arb.

All the values in the array are unique given the provided selector and comparator functions. Two values a and b are considered equal and thus would not be selected together in the same generated array if and only if comparator(selector(a), selector(b)) is true.

If not specified selector defaults to the identity function and comparator defaults to SameValue aka Object.is.

For performance reasons, we highly discourage the use of a fully custom comparator and recommend to rely on a custom selector function whenever possible. Such custom comparator — outside of provided ones — cannot be properly optimized and thus includes a potentially huge performance penalty mostly impacted large arrays.

Signatures:

• fc.uniqueArray(arb)
• fc.uniqueArray(arb, {minLength?, maxLength?, selector?, comparator?, size?, depthIdentifier?})

with:

• arb — arbitrary instance responsible to generate values
• minLength? — default: 0 — minimal length (included)
• maxLength? — default: 0x7fffffff more — maximal length (included)
• selector? — default: v => v — project the generated value in order to compare it
• comparator? — default: SameValue — compare two projected values and returns true whenever the projected values should be considered equal. Possible values for comparator are:
  • SameValue to rely on Object.is to compare items (more details)
  • SameValueZero to rely on the same logic as the one of Set or Map to compare items (more details)
  • IsStrictlyEqual to rely on === to compare items (more details)
  • Fully custom function having the signature: (selectedValueA, seletedValueB) => aIsEqualToB
• size? — default: undefined more — how large should the generated values be?
• depthIdentifier? — default: undefined — when specified, the array will impact the depth attached to the identifier to avoid going too deep if it already generated lots of items for current level

Usages:

fc.uniqueArray(fc.nat(99));
// Examples of generated values: [51,68,39,84,4,40,60], [51,61,41,48,77,59,89,22,83,29], [], [69,52,75,15,34,91,10,87,26,85], [31,4,35,59,9,79,70,94,67]…

fc.uniqueArray(
  fc.record({
    id: fc.nat(),
    name: fc.constantFrom('Anna', 'Paul'),
  }),
  { selector: (entry) => entry.id },
);
// Note: Resulting arrays will never contain two entries having the same id
// Examples of generated values:
// • [{"id":8,"name":"Paul"},{"id":4,"name":"Anna"},{"id":71821146,"name":"Paul"}]
// • [{"id":2049051311,"name":"Anna"},{"id":366741855,"name":"Anna"},{"id":479370052,"name":"Paul"},{"id":1860796933,"name":"Anna"},{"id":1378016577,"name":"Paul"},{"id":337493073,"name":"Paul"},{"id":1057553570,"name":"Paul"},{"id":1232989649,"name":"Anna"}]
// • [{"id":369913425,"name":"Paul"},{"id":16,"name":"Paul"}]
// • [{"id":2147483638,"name":"Paul"},{"id":0,"name":"Paul"},{"id":762515963,"name":"Paul"},{"id":2147483634,"name":"Anna"},{"id":961925886,"name":"Anna"},{"id":2147483618,"name":"Paul"}]
// • [{"id":511407241,"name":"Paul"},{"id":2079170165,"name":"Paul"},{"id":225152957,"name":"Anna"},{"id":777663452,"name":"Paul"},{"id":541492400,"name":"Paul"},{"id":1253009133,"name":"Anna"},{"id":1769176807,"name":"Anna"},{"id":1106486877,"name":"Paul"},{"id":70176060,"name":"Anna"}]
// • …

fc.uniqueArray(fc.constantFrom(-1, -0, 0, 1, Number.NaN));
// Note: By default `uniqueArray` is using `SameValue` algorithm
// so 0 is different from -0 and NaN equals NaN...
// Examples of generated values: [1,-0,Number.NaN], [1,-0], [0,1,-0,-1,Number.NaN], [Number.NaN,1,-1], [-1,-0,1,Number.NaN,0]…

fc.uniqueArray(fc.constantFrom(-1, -0, 0, 1, Number.NaN), { comparator: 'SameValueZero' });
// Note: ...but it could be overriden by `SameValueZero`
// so 0 equals -0 and NaN is equals NaN...
// Examples of generated values: [-0,Number.NaN,1], [Number.NaN,-0,1,-1], [], [0,Number.NaN,-1], [0,-1,1,Number.NaN]…

fc.uniqueArray(fc.constantFrom(-1, -0, 0, 1, Number.NaN), { comparator: 'IsStrictlyEqual' });
// Note: ...or it could be overriden by `IsStrictlyEqual`
// so 0 equals -0 and NaN is different from NaN...
// Examples of generated values: [], [Number.NaN], [0,1], [0,-1,Number.NaN], [-1,0,1]…

fc.uniqueArray(fc.constantFrom(-1, -0, 0, 1, Number.NaN), { comparator: (a, b) => Math.abs(a) === Math.abs(b) });
// Note: ...or overriden by a fully custom comparator function
// With the function defined in this example we will never have 1 and -1 toegther, or 0 and -0 together
// but we will be able to have many times NaN as NaN !== NaN.
// Examples of generated values:
// • [-0,-1,Number.NaN,Number.NaN,Number.NaN,Number.NaN,Number.NaN,Number.NaN]
// • [Number.NaN,-0,-1,Number.NaN,Number.NaN,Number.NaN,Number.NaN,Number.NaN,Number.NaN]
// • [Number.NaN,-0,1,Number.NaN]
// • [-1,-0]
// • [Number.NaN,0,1]
// • …

Resources: API reference.
Available since 2.23.0.

sparseArray

Sparse array of random length containing values generated by arb.

By default, the generated array may end by a hole (see noTrailingHole).

Signatures:

• fc.sparseArray(arb)
• fc.sparseArray(arb, {maxLength?, minNumElements?, maxNumElements?, size?, noTrailingHole?, depthIdentifier?})

with:

• arb — arbitrary instance responsible to generate values
• minNumElements? — default: 0 — minimal number of elements (included)
• maxNumElements? — default: 0x7fffffff more — maximal number of elements (included) - when not specified, the algorithm generating random values will consider it equal to maxGeneratedLengthFromSizeForArbitrary(minNumElements, size) but the shrinking one will use 0x7fffffff
• maxLength? — default: 0x7fffffff more — maximal length (included) - length includes elements but also holes for sparse arrays - when not specified, the algorithm generating random values will consider it equal to maxGeneratedLengthFromSizeForArbitrary(maxNumElements used by generate, size) but the shrinking one will use 0x7fffffff
• size? — default: undefined more — how large should the generated values be?
• noTrailingHole? — default: false — when enabled, all generated arrays will either be the empty array or end by a non-hole
• depthIdentifier? — default: undefined — when specified, the array will impact the depth attached to the identifier to avoid going too deep if it already generated lots of items for current level

Usages:

fc.sparseArray(fc.nat(), { maxLength: 20 });
// Examples of generated values:
// • [1627484989,,,,,,,,,22,,,,,,,,,11]
// • [,,,,,,,,,,,,,,,,,]
// • [1043017167,930550953,,,,498049739,,,,,,,,235141741,,738215975,680577423,,,2064971973]
// • [,,,,,,]
// • [62419385,,1707521378,1036722778,,,,356343941,,,1112723591]
// • …

fc.sparseArray(fc.nat(), { maxLength: 20, minNumElements: 1, maxNumElements: 3 });
// Examples of generated values:
// • [,,,,,,2004160460,,5,,,,,,,]
// • [,,,,,,,,,,,,,10,1247873180,24]
// • [,,,,,,,,,,630417302,,]
// • [,,634971820,827905281,,,,,]
// • [2147483627,,,,,,,24,,,,,,1018653780]
// • …

fc.sparseArray(fc.nat(), { maxLength: 20, noTrailingHole: true });
// Examples of generated values:
// • [,,,,,,,,,,,,,,184571604,,1332679116]
// • [701596391,,13,477087993,,,,,,9,,,,,1837515799,,25,,1052666808]
// • [377875514,,,,,,,,,,382054662,152349138,,410337560,,,,,522248788]
// • [,,,1403559564,,,,,,,,,,,,793214440]
// • [2147483631,,,2147483639]
// • …

fc.sparseArray(fc.nat());
// Examples of generated values:
// • [567750362,,,,,299091021,,,96489016,,430712239,1234134991,,,,1397461705,,,730578007,,357868161]
// • [,,2134637909,,,,,,,,,,,,,,,974140509]
// • [,,,787200555,482854155,,1499996148,,641656016,,,,1222781086,594176416,,,,,,,1481640999,,541444578,,,,1102940112,,,1044037657]
// • [,,1813325449,142891531,1033921636,,,,,,,,,,,,,,,16063768,,,,,,]
// • [,,,,1986457412,,,,1986792467,346901065,,,,1043089270,,,,1052063773,,,,117173340,,1802061561,,,1876841731,2059591309]
// • …

fc.sparseArray(fc.nat(), { size: '+1' });
// Note: By specifying a size higher than the currently configured one, we ask for larger arrays in terms of number of
// elements (see minNumElements and maxNumElements) but also in terms of length (see maxLength).
// Examples of generated values:
// • Object.assign(Array(1200),{498:4,1199:465389025})
// • Object.assign(Array(1154),{10:1275475127,68:1282936956,88:7087106,103:274973107,228:214695477,265:861580584,295:771934152,353:2092009603,399:2045432038,413:2047925581,414:1057390520,471:60415562,520:440518484,535:308102024,606:1012962996,609:1034110033,661:1605711835,758:1994416982,780:1836707994,799:837969364,805:48536112,920:31493298,1118:477398469,1153:1382960253})
// • Object.assign(Array(1198),{14:1265106397,25:1992189706,31:1009542633,37:2103360753,39:2105840658,41:27425052,45:947954479,71:1108948663,86:1920541257,87:1399025075,93:1255551598,97:244052130,105:1557208578,129:1710577472,141:391872683,162:16081929,175:39586497,186:654374742,190:1687117881,287:474014452,342:1105765185,360:1493656073,375:236096982,420:1206486228,436:1628321689,437:749903635,445:1548247725,486:190055012,489:1712264957,536:1601477084,545:1391277520,607:366935947,615:1706042271,650:1371529122,661:436134238,685:579512012,709:1719244372,713:1697974975,734:330762410,740:1565436488,751:653241245,754:294417483,770:1406773247,779:1207966138,831:334418096,880:2109546690,896:4454713,946:1749660318,962:379501736,998:879759299,1031:1199146443,1037:1167013446,1038:108442984,1058:374755399,1061:1537141349,1068:1521525089,1078:1342256788,1080:332676776,1135:2022624121,1155:1828572490,1165:1317565260,1177:2060796612})
// • [,,,,,,,,,]
// • Object.assign(Array(1199),{0:490598143,1:15,2:15,3:1073857704,5:14,7:1574740959,8:447582064,10:2147483625,21:501462968,170:800696723,191:2147483625,208:1027453018,232:368221366,318:553146768,353:691955534,399:1626051171,421:29,443:27,477:5,480:7,581:10,639:1950373478,641:3,656:277325962,690:420312969,710:1113621528,882:2147483625,893:1920703967,947:19,974:9,1000:12,1041:777636885,1086:1283251245,1111:2147483622,1112:2003627018,1185:672201936,1190:2147483638,1191:236447272,1192:1051806815,1193:244597135,1194:2104695915,1195:768174940,1196:3,1198:29})
// • …

Resources: API reference.
Available since 2.13.0.