cucumber_wire 0.1.0+1

cucumber_wire #

Pub Version Build Status Coverage Status

An implementation of cucumber using the cucumber wire protocol.

Usage #

There are several ways to use this package. For a regular use setup a dart project and add this package as a dependency:

name: my_cucumber_features

  cucumber_wire: any

Then setup your features folder containing a .feature file and a step_definitions folder, in which you add a dart_server.wire file including the following content:

host: localhost
port: 9090

Add a step definition dart file which registers the scenarios (ex: features/step_definitions/definitions.dart). The cucumber_wire package exports the package:matcher/matcher.dart so matcher are directly available as well as a simple expect function.

// You may import further tests
import 'package:cucumber_wire/cucumber_wire.dart';

void main(_, SendPort port) {
  // The port is provided by the runner when this step definition dart file is loaded and is used to communicate 
  // between this dart file and the server.
  registerStepDefinitions(sendPort, [

class TestScenario {
  @Given("we're all wired")
  void allWired() {}

  @Then(r'I see the download button with text "([A-Za-z\s+]+)"')
  void openTheBrowser(String text) {
    expect(button.text, text);

  @Then('I want to do something')
  void wantToDoSomething() {
    // ...

Start the cucumber_wire server using pub run pointing to your entry point file.

pub run cucumber_wire features/step_definitions/definitions.dart

Afterwards start your cucumber runner:

cucumber -f pretty

Setting up scenarios #

Scenario classes contain methods which define steps. These steps are annotated with @Then, @And, @Given and @When. The name of the method is not relevant. Within the step annotations a regular expression string is defined, which will be extended by the scenario loader when the scenario is added to registerStepDefinitions, meaning the original expression string: It's a ([a-z]+) will be turned into ^It's a ([a-z]+), to make it a valid expression and save some overhead.

The matches of the regular expression are than passed to the method as parameters when the step is executed, meaning there need to be at least the same number of parameters for a method than potential matches within the pattern. If the parameter type is not of type string, the runner will try to convert the passed value from cucumber into the proper dart type, which is currently only supported for bool (string == "true"), int, double and num.

The scenario needs to have at least one default named constructor (or no constructor at all) in order for the runner to initiate an instance of the scenario.

void main(_, SendPort port) {
  // The port is provided by the runner when this step definition dart file is loaded and is used to communicate 
  // between this dart file and the server.
  registerStepDefinitions(sendPort, [

class TestScenario {
  @Given("we're all wired")
  void allWired() {}

  @Then(r'I see the download button with text "([A-Za-z\s+]+)"')
  void openTheBrowser(String text) {
    expect(button.text, text);

  @Then('I want to do something')
  void wantToDoSomething() {
    // ...

Parameter types #

It's not necessary to always write matchers as regular expression. The built-in parameter types of cucumber are supported as well:

Parameter typeDescriptionRegular expression
{int}Matches integers, for example 71 or -19.([\-\+0-9]+)
{float}Matches floats, for example 3.6, .8 or -9.2.([\+\-0-9\.]+)
{word}Matches words without whitespace, for example banana (but not banana split)([A-Za-z0-9\_\-]+)
{string}Matches single-quoted or double-quoted strings, for example "banana split" or 'banana split' (but not banana split). Only the text between the quotes will be extracted. The quotes themselves are discarded."([A-Za-z0-9.\s]+)"
{}Matches anything.(.*)

Current implementation of worlds #

Currently worlds should be defined as abstract class and shared across scenarios using inheritance. If variables of a world should be initiated only once use getters which refer to a static property of the world.

// Example scenario with multiple worlds.
class MyScenario1 extends DriverWorld with MagicWorld {
  @When('I open the browser at (.*)')
  void openTheBrowser(String url) => driver.get(url);
  @And('I activate magic')
  void activateMagic() => isActive = true;
  @Then('all is good')
  void allIsGood() => expect(allGood, isTrue);
class MyScenario2 extends DriverWorld {}

// A world 
abstract class DriverWorld {
  // Static property so each instance of DriverWorld shares the driver.
  static WebDriver _driver;
  // This getter checks whether _driver is not null, if it is null the initiation expression is executed.
  WebDriver get driver => _driver ??= createDriver();
  void closeDriver() {
    _driver = null;

abstract class MagicWorld {
  // Example of getter and setter usage.
  static bool _isActive = false;
  bool get isActive => _isActive;
  set isActive(bool active) {
    assert(_isActive != active, 'Active cannot be set to the same value twice, something went wrong.');
    _isActive = active;
  // Static variable can also be used instantly
  static bool allGood = true;

Proposal for worlds #

Note: This is a proposal and not yet implemented.

Worlds should be provided by dependency injection.

void main(_, port) {
  registerStepDefinitions(port, [
  ], providers: [

class TestScenario {
  final TestWorld world;

class TestWorld {}

Plugins #

Plugins help to provide further details to a step definition method and do steps before executing the method. Plugins are imported within the step definition and as such can be defined outside of this package. A possible first implementation of a plugin could be cucumber_wire_webdriver which is currently available in features/step_definitions/driver.dart.

A plugin contains a method apply which is called for each step parameter which is not defined by the expression before the method is called.

@When('I open the browser at (.*)')
void openTheBrowserAt(String url, String thisParameterIsForPlugin) {}

The first plugin in the list of registered plugins within registerStepDefinitions which returns an other value than null in it's apply method is used. The apply method receives a ParameterMirror which is used to gather the information of the parameter and as a second argument the instance of the scennario class which contains the method. Therefore the instance of the scenario can be used to gather further information or execute additional steps (which at this point may only be synchronous).

An example for a plugin can be seen below, which enables an annotation for parameters to use the WebDriver to fetch a WebElement using a CSS selector, where the instance of the scenario needs to inherit the Driver world.

/// Example plugin to support build in annotations for CssSelectors.
class ByCssSelectorPlugin extends SuitePlugin<Driver, WebElement> {
  final _by = reflectClass(By);

  WebElement apply(ParameterMirror mirr, Driver instance) {
    final selector = _selector(mirr);
    if (selector != null) {
      return instance.driver.findElement(selector);

    return null;

  By _selector(ParameterMirror mirr) {
    for (final meta in mirr.metadata) {
      if (meta.type.isAssignableTo(_by)) {
        return meta.reflectee;

    return null;

After registering the plugin to the registerStepDefinitions function, it's available to all scenarios registered within the same function as well.

void main(_, SendPort sendPort) {
  registerStepDefinitions(sendPort, [
  ], plugins: [

class TestScenario extends Driver {
  @Then(r'I see the download button with text "([A-Za-z\s+]+)"')
  void openTheBrowser(
      String text, @By.cssSelector('.install-download') WebElement button) {
    expect(button.text, text);

Tools #

Add definition #

This tool generates the step definition method code based on a provided sentence.

Usage: pub run cucumber_wire:add_definition [options] "<sentence>" [target_file] [target_line]

Where <sentence> needs to start with either Given, And, Then or When.

-a, --[no-]async    Defines that the step definition should be asynchronous
-h, --[no-]help     Shows this usage message.

Define it as an external tool within intellij to enable a smooth experience directly in the IDE.

settings tool

settings tool async

usage tool

How it works #

This package is using the cucumber wire protocol to support a dart implementation of cucumber. Therefore a TCP server is started which listens for instructions provided by cucumber when it's started using a .wire configuration file within the step_definitions folder. The dart process which starts the TCP server also spawns an isolate with the given path to the step definitions dart implementation.

The isolate uses reflection to detect all step definitions (@Given, @Then, @When, @And, @after, ...) which are defined within scenarios passed to registerStepDefinitions within the main function. Because the step definition dart file is spawned using an isolate it receives a SendPort as the second argument to the main function, which is passed to registerStepDefinitions which is responsible for the communication between the isolate and parent dart isolate which spawned the TCP server.

When the TCP server receives instructions from the cucumber client it forwards them to the isolate which either:

  • Looks up if the definition exists, which arguments are provided and returns a proper identifier for the method
  • Executes a definition by it's previously provided identifier and the given arguments
  • Executes a hook (@afterAll, @beforeAll, @before, @after)

The implementation which spawns the isolate comes with some features, like change detection and reloading of the isolate.

Known issues #

  • @afterAll, @beforeAll methods on worlds might be executed multiple times, therefore add a bool check whether the method was already executed otherwise skip function. Null operators help in this case _driver ??= createDriver(). _driver?.close(); _driver = null;.

Roadmap #

  • Support configuration with configuration file parameters which are then either passed as environment variables or available for access by injection.
  • Integration with package:test.
  • Support for multiple entry point files.
  • Examples for Intellij live code templates for ease of use.
  • Support asynchronous plugins
  • Dependency injection of scenarios and worlds.
  • Debugging story including running pub run cucumber and providing a debug port.
  • Applying new mixin patterns to worlds and plugins.
  • Add analyzer plugin to validate scenarios, potential analyzer warnings/lints:
    • Number of parameters doesn't match the amount of pattern matches.
    • Step definition already exists in a different scenario.
  • Provide optional arguments and named arguments (@Then('Button label :label should :equal'))

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  cucumber_wire: ^0.1.0+1

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:cucumber_wire/cucumber_wire.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Jul 2, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.9+1

Health issues and suggestions

Fix lib/src/server/wire_server.dart. (-44.03 points)

Analysis of lib/src/server/wire_server.dart failed with 2 errors, 1 hint:

line 38 col 26: The argument type 'Utf8Decoder' can't be assigned to the parameter type 'StreamTransformer<Uint8List, dynamic>'.

line 40 col 20: The argument type 'WireMessage Function(String)' can't be assigned to the parameter type 'dynamic Function(dynamic)'.

line 27 col 50: This function has a return type of 'FutureOr

Fix bin/add_definition.dart. (-0.50 points)

Analysis of bin/add_definition.dart reported 1 hint:

line 27 col 16: Avoid empty catch blocks.

Fix bin/cucumber_wire.dart. (-0.50 points)

Analysis of bin/cucumber_wire.dart reported 1 hint:

line 11 col 5: Future results in async function bodies must be awaited or marked unawaited using package:pedantic.

Fix lib/cucumber_wire.dart. (-0.50 points)

Analysis of lib/cucumber_wire.dart reported 1 hint:

line 17 col 67: The library 'package:cucumber_wire/src/frontend/frontend.dart' doesn't export a member with the shown name 'expect'.

Maintenance issues and suggestions

No valid SDK. (-20 points)

The analysis could not detect a valid SDK that can use this package.

Provide a file named (-20 points)

Changelog entries help developers follow the progress of your package. See the example generated by stagehand.

Support latest dependencies. (-10 points)

The version constraint in pubspec.yaml does not support the latest published versions for 1 dependency (cli_util).

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and cucumber_wire.dart. Packages with multiple examples should provide example/

For more information see the pub package layout conventions.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
args ^1.5.0 1.6.0
cli_util ^0.1.3 0.1.4 0.2.0
matcher ^0.12.0 0.12.8
meta ^1.1.0 1.1.8 1.2.0
path ^1.6.0 1.7.0
test ^1.3.0 1.15.1
watcher ^0.9.0 0.9.7+15
webdriver ^2.0.0 2.1.2
Transitive dependencies
_fe_analyzer_shared 5.0.0
analyzer 0.39.11
archive 2.0.13
async 2.4.1
boolean_selector 2.0.0
charcode 1.1.3
collection 1.14.13
convert 2.1.1
coverage 0.14.0
crypto 2.1.5
csslib 0.16.1
glob 1.2.0
html 0.14.0+3
http 0.12.1
http_multi_server 2.2.0
http_parser 3.1.4
io 0.3.4
js 0.6.2
logging 0.11.4
mime 0.9.6+3
node_interop 1.1.1
node_io 1.1.1
node_preamble 1.4.12
package_config 1.9.3
pool 1.4.0
pub_semver 1.4.4
shelf 0.7.7
shelf_packages_handler 2.0.0
shelf_static 0.2.8
shelf_web_socket 0.2.3
source_map_stack_trace 2.0.0
source_maps 0.10.9
source_span 1.7.0
stack_trace 1.9.5
stream_channel 2.0.0
string_scanner 1.0.5
sync_http 0.2.0
term_glyph 1.1.0
test_api 0.2.17
test_core 0.3.9
typed_data 1.2.0
vm_service 4.1.0
web_socket_channel 1.1.0
webkit_inspection_protocol 0.7.3
yaml 2.2.1
Dev dependencies
dart_coveralls ^0.6.0
mockito ^3.0.0
pedantic ^1.1.0 1.9.0 1.9.1