Merge pull request #11 from gmaxlev/website

Website

README.md

@@ -18,7 +18,7 @@ Imagine you have a function for creating order that accepts 6 parameters with se
 
 | Parameter      | Possible Values                          |
 | -------------- | ---------------------------------------- |
-| Location       | Ukraine, Poland, Lithuania, Germany, USA |
+| Location       | Poland, Lithuania, Germany, USA          |
 | Customer       | Individuals, Companies, Partners         |
 | Time           | 05:00, 11:99, 15:00, 21:30, 23:59        |
 | Payment System | VISA, MasterCard, PayPal, WebMoney, Qiwi |
@@ -33,7 +33,7 @@ import { pict } from "pict-node";
 const model = [
   {
     key: "location",
-    values: ["Ukraine", "Poland", "Lithuania", "Germany", "USA"],
+    values: ["Poland", "Lithuania", "Germany", "USA"],
   },
   {
     key: "customer",
@@ -96,7 +96,7 @@ PICT will generate the following test cases:
   },
   // ... ... ...
   {
-    location: "Ukraine",
+    location: "Poland",
     customer: "Companies",
     time: "23:59",
     paymentSystem: "MasterCard",
@@ -107,9 +107,9 @@ PICT will generate the following test cases:
 ];
 ```
 
-## Generating Test Cases
+## Create Test Cases
 
-In most cases, to generate test cases, you can use the `pict` function. The main features of this function is that you can use any data type for the values of the model.
+In most cases, to create test cases, you can use the `pict` function. The main feature of this function is that you can use any data type for the values.
 
 ```js
 import { pict } from "pict-node";
@@ -119,7 +119,7 @@ import { createOrder } from "./src";
 const model = [
   {
     key: "country",
-    values: ["Ukraine", "Poland", "USA"],
+    values: ["USA", "Canada", "Germany"],
   },
   {
     key: "age",
@@ -163,6 +163,8 @@ const cases = await pict(
 
 ## TypeScript 🪄
 
+The library provides excellent support for TypeScript.
+
 Here is an example of using this tool with TypeScript:
 
 ```ts
@@ -194,7 +196,7 @@ Array<{
 }>;
 ```
 
-**⚠️ Note that we use `as const` to get a literal types!**
+> ⚠️ Note that we use `as const` to get a literal types!\*\*
 
 Without `as const` the type of `cases` will be:
 
@@ -207,6 +209,8 @@ Array<{
 
 ## Constraints
 
+In practice, you might want to exclude some of the generated test cases because certain parameters can't exist together. You can use constraints and their powerful syntax for this.
+
 > Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#constraints) to get more information about constraints.
 
 Constraints are only applicable when using the `strings` function, which only accepts `string` values and provides additional options:
@@ -256,6 +260,9 @@ If you need to use values of different types, you can use the `pict` function in
 
 ## Sub-Models
 
+Sub-models allow the bundling of certain parameters into groups that get their own combinatory orders.
+This can be useful if combinations of certain parameters need to be tested more thoroughly, or less thoroughly, or in separation from the other parameters in the model.
+
 > Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#sub-models) to get more information about sub-models.
 
 Sub-models can be used with both the `pict` and `strings` API functions, and they are defined using the `sub` property.
@@ -297,6 +304,8 @@ const cases = await pict({
 
 ## Seeding
 
+Seeding allows for specifying important e.g. regression-inducing combinations that should end up in any generated test suite.
+
 > Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#seeding) to get more information about seeding.
 
 Seeding can be used with both the `pict` and `strings` API functions, and they are defined using the `seed` property.
@@ -343,6 +352,11 @@ const cases = await pict({
 
 ## Aliasing
 
+Aliasing is a way of specifying multiple names for a single value. Multiple names do not change the combinatorial complexity of the model.
+No matter how many names a value has, they are treated as one entity.
+The only difference will be in the output; any test case that would normally have that one value will have one of its names instead.
+Names are rotated among the test cases.
+
 > Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#aliasing) to get more information about aliasing.
 
 There is a special function `alias` that can be used to create aliases for values. It can be used with both the `pict` and `strings` API functions.
@@ -370,6 +384,8 @@ const cases = await pict({ model });
 
 ## Negative Testing
 
+In addition to testing valid combinations, referred to as “positive testing,” it is often desirable to test using values outside the allowable range to make sure the program handles errors properly.
+
 > Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#negative-testing) to get more information about negative testing.
 
 There is a special function `negative` that can be used to create a value for negative testing. It can be used with both the `pict` and `strings` API functions.
@@ -393,6 +409,10 @@ const cases = await pict({ model });
 
 ## Weighting
 
+Weights tell the generator to prefer certain parameter values over others.
+Weights are positive integers.
+When not explicitly specified, values have a weight of 1:
+
 > Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#weighting) to get more information about weighting.
 
 There is a special function `weight` that can be used to create a value with weight. It can be used with both the `pict` and `strings` API functions.
@@ -420,14 +440,17 @@ const cases = await pict({ model });
 
 ## Randomization
 
+If a model and options given to the tool do not change, every run will result in the same output.
+However, the output can be randomized.
+
 > Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#output-format) to get more information about randomization.
 
 If the model does not change, running it repeatedly will result in the same output. To introduce randomness, you can use the `random` option.
 
 It applies to `pict`, `strings` and `native` API.
 
 ```js
-import { pict, negative } from "pict-node";
+import { pict } from "pict-node";
 
 const model = [
   // ...
@@ -476,7 +499,7 @@ A model and a seed can be a string:
 ```js
 import { native } from "pict-node";
 
-const cases = native({
+const cases = await native({
   model: `
   PLATFORM:  x86, x64, arm
   RAM:       1GB, 4GB, 64GB

web/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

web/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

web/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve("@docusaurus/core/lib/babel/preset")],
+};

web/docs/aliasing.mdx

@@ -0,0 +1,34 @@
+---
+sidebar_position: 7
+---
+
+# Aliasing
+
+Aliasing is a way of specifying multiple names for a single value. Multiple names do not change the combinatorial complexity of the model. No matter how many names a value has, they are treated as one entity. The only difference will be in the output; any test case that would normally have that one value will have one of its names instead. Names are rotated among the test cases.
+
+:::info
+Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#aliasing) to get more information about aliasing.
+:::
+
+There is a special function `alias` that can be used to create aliases for values. It can be used with both the `pict` and `strings` API functions.
+
+```js
+import { pict, alias } from "pict-node";
+
+const model = [
+  {
+    key: "os",
+    values: ["Win7", "Win8", alias(["Win10", "Windows10"])],
+  },
+  {
+    key: "platform",
+    values: ["x86", "x64", "arm"],
+  },
+  {
+    key: "ram",
+    values: [1, 4, 64],
+  },
+];
+
+const cases = await pict({ model });
+```

web/docs/constraints.mdx

@@ -0,0 +1,58 @@
+---
+sidebar_position: 4
+---
+
+# Constraints
+
+In practice, you might want to exclude some of the generated test cases because certain parameters can't exist together. You can use constraints and their powerful syntax for this.
+
+:::info
+Read [PICT documentation](https://github.com/Microsoft/pict/blob/main/doc/pict.md#constraints) to get more information about constraints.
+:::
+
+Constraints are only applicable when using the strings function, which only accepts string values and provides additional options:
+
+- `aliasSeparator` - the separator used for aliases (default: `|`)
+- `valueSeparator` - the separator used for values (default: `,`)
+- `negativePrefix` - the prefix used for negative values (default: `~`)
+- `caseSensitive` - [case sensitive](https://github.com/Microsoft/pict/blob/main/doc/pict.md#case-sensitiveness) (default: `false`)
+
+:::warning
+Be aware that the characters used for `aliasSeparator`, `valueSeparator`, and `negativePrefix` cannot be used in your values. If you use them, you must replace them using the second argument (options).
+:::
+
+```js
+import { strings } from "pict-node";
+
+const model = [
+  {
+    key: "type",
+    values: ["Primary", "Logical", "Single"],
+  },
+  {
+    key: "size",
+    values: ["10", "100", "500", "1000", "5000", "10000", "40000"],
+  },
+  {
+    key: "fileSystem",
+    values: ["FAT", "FAT32", "NTFS"],
+  },
+];
+
+const constraints = [
+  'IF [fileSystem] = "FAT"   THEN [Size] <= 4096;',
+  'IF [fileSystem] = "FAT32" THEN [Size] <= 32000;',
+];
+
+const cases = await strings(
+  {
+    model,
+    constraints,
+  },
+  {
+    caseSensitive: true,
+  }
+);
+```
+
+If you need to use values of different types, you can use the `pict` function instead of the `strings` function. This way, you can specify any type you want for the values of your model.