petri-specs

petri-specs is a CLI tool used to generate a json spec file that defines the experiments aspects used by petri.

• Create new spec
• Building specs
• Publishing specs
  • Automatic specs scanning
  • Use the publish command
• Configuration
  • defaultScopes
  • scopes
  • owner
  • signature
  • defaultVariants
  • defaultControlGroup
  • multipleScopesSelection
  • customScopeOption
  • multiVariantQuestion
  • defaultNamespace
  • allowedForBots
  • exposureRuleQuestion
  • description
  • disclaimer
  • specNamePrefix
  • specNameSeparator
  • specNameRegexValidation
  • The Scope object
• Creating experiments
• ab-translate
• Setup for non yoshi projects
• Eco-system related links

Create new spec

Generate a local json spec file under <project-root>/petri-specs/specs.<specName>.json:

> npx petri-specs new

[?] Spec name: specs.<myNamespace>.<MySpecName> (specs.cx.IsMyButtonBig)
[?] Scope Names (seperated by ','): <scope-name1>,<scope-name2>,... (my-account)
[?] Ownership tag : (fed-infra)
[?] Scope Type: (Use arrow keys)

> Only for logged in users
  All user types

Building specs

A project may have several specs in it. It is required to combine them before publishing.

You can do this yourself by running npx petri-specs build. If you're using Yoshi, it does this for you during build in the CI.

This will create a dist/statics/petri-experiments.json file combining all your specs, ready for specs-feeder to pick it up in the CI.

Publishing specs

Before you can create an experiment from a spec, you should publish it to laboratory-server.

Automatic specs scanning

When you push your code to master, specs-feeder will scan for the combined petri-experiments.json file, and publish your specs.

Use the publish command

When you add or update a spec file in your local environment you can run the publish command in order to quickly add the spec to the laboratory-server.

petri-specs publish

It uses a local file .petri-specs-hash which should be added to your git repository, in order to optimize the calls to the server.

Notice - you have to be connected to VPN to use this command

Configuration

.petrirc / petri.config.js

Place the configuration file on the root of your project and petri will use it to customize it's behavior:

defaultScopes

Array of {"name": string; "value": Scope} (default [])

These scope values will always be added to the spec file.

scopes

Array of Scope Objects (default [])

These scope values will be added as a multiple choices question when choosing scope names.

owner

undefined | String | Array<String> (default undefined)

Ownership tag of the team, use this property for setting the default ownership tag, if multiple ownership tags are chosen, a multiple choices question will be presented to the developer when creating a new spec.

signature

Boolean (default false)

Sign each spec with a signature to verify it won't be updated manually (only using the "petri-specs new" command).

defaultVariants

String (default ['true'])

Configure the default variants.

defaultControlGroup

String (default 'false')

Configure the default controlGroup.

multipleScopesSelection

Boolean (default true)

Change the checkboxes on the scope selection into mutually exclusive radio buttons.

customScopeOption

Boolean (default true)

A way to disable the customScope option during the scopes selection.

multiVariantQuestion

Boolean (default false)

Ask whether you want to choose multi-variants, in case you do, you'll be prompted with 2 questions for you custom controlGroup and variants.

defaultNamespace

String? (default undefined)

Will be preconfigured when asked for spec name

allowedForBots

Boolean (default false)

Whether conduction should be made for bots requests, read more.

exposureRuleQuestion

Boolean (default false)

Ask the user if he/she wants to add an exposure-rule id, this will help BI cross-reference specs and events (exposure_rule).

description

Boolean (default false)

An option that if configured as true will request the user for description and will use it in the specs.

disclaimer

Function? or String? (default undefined)

An optional message that would be printed to the console in the end of the spec creation process. Could also be a function (in this case, your config file must be a javascript file), in order to be able to condition the disclaimer upon user's answers. For example:

disclaimer: (answers) => {
    if (answers.scope[0].name === 'thunderbolt-preview-site-owner') {
      return 'this is a specific warning';
    } else {
      return 'this is a general warning';
    }
  }

specNamePrefix

Boolean (default true)

Can be configured to false in order to remove the specs prefix for each spec name when using petri-specs new

specNameSeparator

String (default .)

Can be used in order to change the separator used between the specs prefix, the namespace and the spec name, for example, if configured to _ generating a new spec may yield the following spec: specs_team_name instead of the default specs.team.name

specNameRegexValidation

String [regex] (default [a-zA-Z0-9_]+)

A way to validate the spec name upon spec creation, please note that the namespace won't be validated or the separator which can be configured using defaultNamespace & specNameSeparator configuration options.

For example, in the following spec name specs.namespace.specName only the specName part will be validated by the regex.

Note that ^ & $ are added automatically and you don't need to add them to the validation regex.

loggedInUsersSuffix

String

When configured, this suffix will be added to multi-audience specs during spec creation (specs that are configured to work with both unknown users and logged in users).

The suffix will be added for the logged in scopes.

{
"loggedInUsersSuffix": "_preview",
"scopes": [
  {
    "name": "Both Scopes (with preview)",
    "persistence": true,
    "value": [
      { "name": "bolt-preview", "onlyForLoggedInUsers": true },
      { "name": "bolt-viewer", "onlyForLoggedInUsers": false }
    ]
  }]
}

The above configuration will generate 2 specs:

specs.thunderbolt.my-spec (for bolt viewer)
specs.thunderbolt.my-spec_preview (for bolt preview)

The Scope object

type Scope = {
  name: string; // The user will see this when choosing the scope
  value: ScopeValue | Array<ScopeValue>; // The value that will be used in the created spec
  persistence?: boolean; // will be used for the whole spec if this scope option is chosen
};

type ScopeValue =
  | {
      name: string; // the name that will be used
      onlyForLoggedInUsers: boolean; // will be configured per scope
    }
  | string; // the name that will be used for the simple case

example configs:

Simple

.petrirc

{
  "owner": "amazing-team",
  "defaultScopes": [{ "name": "logo-builder", "value": "logo-builder" }],
  "scopes": [
    { "name": "Server", "value": "logo-builder" },
    { "name": "Client", "value": "logo-builder-client" }
  ],
  "signature": true
}

More complex

petri.config.js

module.exports = {
  signature: true,
  multiVariantQuestion: true,
  defaultVariants: ['new'],
  defaultControlGroup: 'old',
  multipleScopesSelection: false,
  customScopeOption: false,
  description: true,
  allowedForBots: true,
  defaultNamespace: 'thunderbolt',
  scopes: [
    {
      name: 'Both Scopes (with preview)',
      persistence: true,
      value: [
        { name: 'bolt-preview', onlyForLoggedInUsers: true },
        { name: 'bolt-viewer', onlyForLoggedInUsers: false },
      ],
    },
    {
      name: 'Public Only',
      persistence: false,
      value: [{ name: 'bolt-viewer', onlyForLoggedInUsers: false }],
    },
  ],
};

Creating experiments

After publishing the spec, it will become visible on guineapig. You will now be able to create a new experiment out of it. Read more about it here.

ab-translate

ab-translate runs when running petri-specs build. If you want to configure it, you can do so using .petrirc/petri.config.js:

"abTranslate": {
  "onlyForLoggedInUsers": false, // default: true
  "scopes": ["my-projects-translation-scope"] // default: [<artifactId>]
}

Setup for non yoshi projects

Eco-system related links

specs feeder - Runs in the CI, pick up petri-experiments.json spec files and publish them to petri.

proto definition - The Proto definition of the petri server.

petri-specs-gateway - The proxy server that petri-specs publish communicates with.