PHERKIN(1p)

💖 PHERKIN 💖

okay bestie, welcome to the pherkin page from the User Contributed Perl Documentation crew 🫶 this is the little command that runs your tests when you wrote them with Test::BDD::Cucumber. she's giving test-runner but make it fashion 💅

---

✨ VERSION ✨

version 0.87 — yes she's got a number, she's official 💖

---

🌸 SYNOPSIS 🌸

 pherkin
 pherkin some/path/features/

literally that's it. two whole ways to summon her 😌

---

🦋 DESCRIPTION 🦋

okay so pherkin takes one single argument, and it's a directory name. don't give her one? she just defaults to ./features/ like the low-maintenance queen she is 💅

she goes rummaging through that directory looking for two things:

• feature files — any file matching *.feature
• step definition files — any file matching *_steps.pl

then she loads up all the step definitions, and then runs the features. order matters, bestie 🎀

now for the aesthetic: steps that pass get printed in green, steps that fail get printed in red, and steps with no step definition at all — or steps that got skipped because something before them failed — come out yellow. it's giving traffic light but emotionally 😭

and here's the important bit: pherkin exits with a non-zero status if and only if the overall result is considered to be failing. if and only if. she's precise about it. no cap 🫶

---

✨ OPTIONS ✨

💜 Controlling @INC

• -l, --lib — adds lib to @INC
• -b, --blib — adds blib/lib and blib/arch to @INC
• -I [dir] — adds the directory you hand her to @INC

🔥 Controlling Execution

• -m, --match — only match steps in from features with available ones
• --matching [mode] — what she does when a step function matches multiple times. first (the default) just selects the first match, relaxed warns you and then runs the first match anyway, and strict stops execution entirely
• --strict — requires steps to actually be defined; fails on undefined steps and on pending steps (you know, the ones that force 'skip')

🎀 Output formatting

• -o, --output — which output harness to use. defaults to 'TermColor'. peep the 'Outputs' section below, she's got range
• -c, --theme — the theme for 'TermColor'. your options are light or dark (and dark is the default, obviously 🌙)

🌈 Extra Steps

• -s, --steps [path] — include an extra step file, or a whole directory of step files (she identifies them by *_steps.pl, and yes you can use this multiple times, stack 'em up 💅)

🌸 Tag specifications

• -t, --tags <expr> — run the scenarios whose tags satisfy the cucumber tag expression <expr>

💖 Configuration profiles (peep CONFIGURATION PROFILES below, or just run man pherkin)

• -g, --config [path] — a YAML file containing configuration profiles
• -p, --profile [name] — the name of the profile to load from that config file. defaults to default
• --debug-profile — shows you info about which profile got loaded and how, and then she terminates. like, immediately. gone. 👋

🧚 Extensions

• -e Extension::Module — load an extension. and listen, this one's cute: you can stick a string in brackets at the end of the module name, and that string gets eval'd and passed to new() for the extension. slay ✨

⭐ Help

• --version — print the version number.
• -h, -?, --help — print usage information.
• --i18n LANG — list the keywords for a particular language. and '--i18n help' lists every language available 🌍

---

💅 OUTPUTS 💅

pherkin can output using any of the Test::BDD::Cucumber::Harness output modules. TermColor is the default, but TAP is also a totally reasonable option, fr fr:

 pherkin -o TermColor some/path/feature   # The default
 pherkin -o TAP some/path/feature         # TAP text output (for e.g. prove)

---

👑 CONFIGURATION PROFILES 👑

you can specify whole sets of command line options using a YAML configuration file with named profiles in it, plus the -g, --config and -p, --profile command line options. it's giving preset vibes 💅

if you don't specify a config file, she searches these paths in this order looking for one:

 (contents of $ENV{'PHERKIN_CONFIG'})
 .pherkin.yaml
 ./config/pherkin.yaml
 ./.config/pherkin.yaml
 t/.pherkin.yaml
 ~/.pherkin.yaml

the contents of each profile get merged in exactly as if you'd typed it on the command line. and default is what she uses if you didn't specify one. for example:

 default:
   steps:
     - foo/steps
     - ~/steps
   output: TermColor
   tags: @tag1 or @tag2

is equivalent to:

  --steps foo/steps --steps ~/steps --output TermColor --tags '@tag1 or @tag2'

and if you specify both command-line options and options in a config file? the command-line ones override single-value items, and they get placed at the end of multi-item ones. rules are rules 🫶

if you specify --debug-profile, then info showing which profile is loaded and how gets printed to STDOUT, and then pherkin terminates. bye bestie 😭

🌟 EXTENSION CONFIGURATION 🌟

extensions named in the extensions section of the configuration get loaded with the configuration from the configuration file:

 default:
   includes:
      # include location where extensions reside on disk
      - t/lib
   extensions:
      # extension with configuration
      Test::CucumberPush:
          key1: value1
          key2: value2
      # extension without configuration
      Test::CucumberPop:

now pay attention because this is the plot twist: contrary to all other configuration parameters, the names of the extensions are not prefixed with a dash. so it's - t/lib vs Test::CucumberPush. different energy entirely ✨

the example above is the equivalent of:

  use Test::CucumberPush;
  use Test::CucumberPop;

  Test::CucumberPush->new({ 'key1' => 'value1', 'key2' => 'value2' });
  Test::CucumberPop->new();

---

🎀 AUTHOR 🎀

Peter Sergeant pete@clueball.com — icon behavior, honestly 👑

---

🌈 LICENSE 🌈

Copyright 2012-2014, Peter Sergeant; Licensed under the same terms as Perl

---

okay that's the whole page bestie, you ate it 💖 this was perl v5.40.1, dated 2025-05-29, and it's the PHERKIN(1p) page — go run some features, periodt 🌸🦋