How to override task description?

[eyesopen]

I like to provide informative descriptions to my tasks. I was successfully using toString() method before, the provided description would then be printed to reports and it could have been constructed when all the class variables were initialized. This no longer works. How could I override the message provided at the constructor later in the class?

Illustrative example:

class Modify extends Task {
  static basket() {
    return new Modify();
  }

  add(item) {
    this.item = item;
    return this;
  }

  constructor() {
    super('#actor does something'); //this was mandatory
  }
  toString() { //this would override generic string provided in constructor
    return `#actor adds ${this.item} to the basket`;
  }
  performAs(actor) { }
}

Here in the constructor i do not yet know the this.item that i need for the description of the task, but it is accessible when performAs is called.

I did some digging arround and found that this.setDescription(``#actor adds ${this.item} to the basket``) could potentially solve the issue and it prints to report nicely, but it is quite inconvenient...

  constructor() {
    super('#actor does something');
    this.setDescription(`#actor adds ${this.item} to the basket`); //this is reported as undefined instead of item  :(
  }

this below works, but makes some duplication

  add(item) {
    this.item = item;
    this.setDescription(`#actor adds ${this.item} to the basket`);
    return this;
  }

  constructor() {
    super('#actor does something');
  }

  add(item) {
    this.item = item;
    this.setDescription(`#actor adds ${this.item} to the basket ${this.tw?'twice': ''}`); 
    return this;
  }
  twice(){
     this.tw = true;
     this.setDescription(`#actor adds ${this.item} to the basket ${this.tw?'twice': ''}`);
  }

Modify.basket().add('pie'),
Modify.basket().add('doughnut').twice(),
Modify.basket().twice().add('strawberry'),

[jan-molak]

Dynamic descriptions, introduced in Serenity/JS 3.24, separate the static and dynamic descriptions of the activities.

The "static" description is determined right before the actor performs a given activity by calling activity.toString(): string method, where the returned value is included in the ActivityStarts event. This behaviour is consistent with Serenity/JS pre-3.24.

The "dynamic" description is enabled by the newly introduced Describable interface, which allows the actor to retrieve the description of the activity right after it has been performed and when the values of its parameters are already resolved. This is done by calling activity.describedBy(actor): Promise<string> method, and the returned value is included in the ActivityFinished, as you can see in the ability to PerformActivities.

The quick and dirty approach

To override the dynamic description, you could provide the static description when invoking super, and override describedBy method in your custom activity:

class Modify extends Task {
  static basket() {
    return new Modify();
  }

  add(item) {
    this.item = item;
    return this;
  }

  constructor() {
    super('#actor does something'); // static description
  }
  
  override describedBy(actor: Actor): Promise<string> {
    return actor.answer(the`#actor adds ${this.item} to the basket`)
  }
  
  performAs(actor) { }
}

While this works, it might result in the Modify class taking on too much responsibility if the number of optional parameters is large.

In your post, you allude to a fairly sophisticated DSL:

Modify.basket().add('pie'),
Modify.basket().add('doughnut').twice(),
Modify.basket().twice().add('strawberry'),

Let's then explore other design options.

The recommended approach

The recommended approach when developing custom activities is to use the to create a dynamic wrapper around the description, for example:

import { Task, Answerable, the } from '@serenity-js/core';

// inheritance-based implementation
class AddItem extends Task {
  constructor(private readonly item: Answerable<string>) {
    super(the`#actor adds ${ item } to basket`);
  }
}

// alternative, functional style implementation
const AddItem = (item: Answerable<string>) => 
  Task.where(the`#actor adds ${ item } to basket`, /* ... */),

However, this design approach requires the parameter reference (i.e. item) to be available at construction time.

In your case, when the activity is instantiated, we don't know the value of the item or even if it will be set at all.

Separating configuration from instantiation

One approach to solve it could be to separate the problem of parameterising the activity from instantiating the activity. Let's then introduce a class called Basket. This class will offer an entry point for the team to discover all the activities an actor can perform with the basket.

Implementing the Factory Method design pattern

If the activity to add an item to the basket needs only one parameter, we can implement it following the factory method design pattern:

class Basket {
  static addItem(item: Answerable<string>) {
    return new AddItem(item);
  }
}

Here, the static factory method Basket.addItem parameterises the activity and returns it.
The same approach works for methods with no parameters, too

Instantiating activities with multiple required parameters

If the activity to add an item required two or more parameters, say item and quantity, and all of them, or at least a significant majority, were required - we could simply introduce another parameter, maybe with the default value:

class Basket {
  static addItem(item: Answerable<string>, quantity: Answerable<number> = 1) {
    return new AddItem(item, quantity);
  }
}

This design works fine as long as the number of parameters is low and most or all of them are required.
However, if the number of parameters is large, or there's a significant number of optional parameters, this design is no longer sufficient.

Configuring the Factory Method with an Options Object

To extend our design to support instantiating activities with a variable number of parameters, we could modify the Basket.addItem method to accept an options object instead of the individual parameters.

To implement an options object pattern, we'd introduce an interface like AddItemOptions describing what options are available and which ones are required:

interface AddItemOptions {
  item: Answerable<string>;       // required
  quantity?: Answerable<number>;  // optional
}

We'd then modify the Basket.addItem to accept the options object and possibly use object restructuring to provide the default values:

class Basket {
  static addItem({ item, quantity = 1 }: AddItemOptions) {
    return new AddItem(item, quantity);
  }
}

Configuring the Factory Method with a Builder

An alternative to the Options Object pattern is to implement the Builder pattern.

To do that, we'd introduce the basic builder interface, like this:

interface ActivityBuilder {
  build(): Activity
}

Then, assuming that the different activities an actor could perform with the basket required different sets of options, we could have activity-specific builders:

class Item implements ActivityBuilder {
  private quantity: Answerable<number> = 1;

  static called(name: Answerable<string>) {
    return new Item(name);
  }
  
  constructor(private readonly name: Answerable<string>) {
  }
  
  twice() {
    this.quantity = 2;
    return this;
  }
  
  times(quantity: Answerable<number>) {
    this.quantity = quantity;
    return this;
  }
  
  build() {
    return Task.where(the`#actor adds ${ quantity } x ${ this.name } to the basket`, /* */)
  }
}

Finally, we'd modify the Basket to accept the ActivityBuilder instead of the parameters:

class Basket {
  add(item: Item): Activity {
    return item.build();
  }
}

This design enables quite a nice modular DSL:

await actor.attemptsTo(
  Basket.add(Item.called('pie').twice()),
)