serenity-js best practices

[tremkonzah]

Hi,

What is the best practices for serenity-js?
especially for the directory structure

from serenity-js-getting-started it have page object in ui
but the feature and test file all in one directory

what is the best practices for this?

thx

[jan-molak]

Hi @tremkonzah and apologies for being slow to reply on this.

As per our email conversation, "acceptance testing best practices" is a huge topic.
I started answering some of your questions in the "Serenity/JS Handbook" that's now available at serenity-js.org

I made a recommendation for some basic structure in the updated version of the "From Scripts to Serenity" tutorial.

Slice by type

Assuming you keep the test code under spec, and your application uses some imaginary "date picker" UI widget, you could organise your codebase _by type_.

This is a very simple structure that puts the ui components together in one directory, the tasks in another one and so on. This conceptually resembles the design of many MVC frameworks, where you'd have all the controllers in one place, all the models in another.

└── screenplay
    ├── components
    │   ├── date_picker.ts  <- contains targets and questions
    │   └── ...             <- other ui components, like "login_form.ts", "basket.ts" and so on
    └── tasks
        ├── open_date_picker.ts
        ├── close_date_picker.ts
        ├── pick_a_date.ts
        └── ...             <- other tasks related to other widgets, like "add_a_product.ts"

• 👍 The advantage of this structure is that it's very easy to start with, especially when you've just started working on a test suite and don't want to commit yourself to any particular design just yet. Options have value.
• 👎 The disadvantage is that if your application domain is complex, this slicing might not be sufficient for long, and you might end up with loads of files under tasks. This could negatively affect discoverability of your code.

Having said that, you can always start with this structure and refactor to a different one when changing it adds value.

One of the many benefits of using TypeScript is that it'll tell you straight away if by moving files around you've broken anything. It just won't compile :-)

Slice by component

Once the range and variation of the UI components you're working with starts to stabilise, you can try to slice the codebase _by component_.

If we take our imaginary date picker example again, we could propose the following structure:

└── screenplay
    ├── components
    │   ├── date_picker
    │   │   ├── components
    │   │   │   └── date_picker.ts  <- contains targets and questions
    │   │   ├── index.ts            <- exposes the tasks to test scenarios
    │   │   └── tasks
    │   │       ├── open_date_picker.ts
    │   │       ├── close_date_picker.ts
    │   │       └── pick_a_date.ts
    │   │ 
    │   └── ...    <- other ui components, like "login_form.ts", "basket.ts" and so on
    └── tasks
        └── ...    <- other tasks related to other widgets, like "add_a_product.ts"

• 👍 The advantage is that it improves the discoverability of your code - it's obvious what tasks are associated with the date picker here
• 👍 It provides additional encapsulation, the index.ts only exposes the tasks, not the definition of the component structure (targets and questions)
• 👍 It can co-exist in the directory structure described in the previous example, when you slice by type, so you can refactor to this design later.
• 👎 This only works with well-defined UI widgets, that have enough functionality to justify the overhead of the directory structure (creating directories for each drop down of a search filter is an overkill, creating a directory for the _search component_ makes more sense)
• 👎 It's an overkill to start with. As with any design pattern, it works best if you think of it as a goal you might reach, rather than a starting point.

There are several other ways to do it though, and I just realised I should write a post about it ;-)

To summarise, start with slicing by type, and extract components when you learn more about them.

Hope this helps!
Jan

[cmelion]

The file organization under:
https://github.com/jan-molak/serenity-js-getting-started/tree/2-reports/src/screenplay

is different from:
https://github.com/serenity-js/tutorial-from-scripts-to-serenity/tree/2-reports/spec/screenplay

which is considered current best practice and why?

[jan-molak]

My current approach to organising the files relies on continuous evolution and refactoring and could be summarised like this:

• I start with one file, say screenplay.ts where I put all the tasks, interactions, questions and page objects. This helps me to get started with running the scenarios quickly without worrying too much about the structure at this stage:

└── screenplay.ts

• As soon as the file becomes "too heavy" (it defines more than say 15-20 _"things"_) I split it up - in terms of timing, this might happen within a couple of hours from the point in time when I created the original screenplay.ts, so that file is rather short-lived. Also, I use the Task.where(), Interaction.where(), Question.about() syntax to keep the definitions short and compact.
• When it comes to UI-based test automation, I prefer to slice by component, so as soon as I have a couple of test scenarios working with my original screenplay.ts and a couple of logical components identified, I create files for those components where I move tasks and page objects that deal only with those specific components.
• At that point my directory structure might look like this:

├── basket.ts       <- task, questions, interactions and page objects for the basket widget
├── date_picker.ts  <- task, questions, interactions and page objects for date picker widget
└── screenplay.ts

• As my understanding of each individual component evolves, and I add more page objects, tasks, interactions and questions, I split the component file and turn it into a directory to make the contents easier to find. If at this stage I have identified additional sub-components, I create the "component files" for those:

├── basket                   <- sub-components of the basket component
│   ├── saved_for_later.ts
│   ├── summary.ts
│   ├── recently_viewed.ts
│   └── screenplay.ts        <- anything basket-related that doesn't fit within any of the sub-components
├── date_picker.ts
└── screenplay.ts

• At some point my screenplay.ts files will only contain tasks as questions, interactions and page objects will be placed together with their respective components. If that's the case I rename screenplay.ts to tasks.ts as it only has one responsibility of defining the tasks overarching several components.

├── basket
│   ├── saved_for_later.ts
│   ├── summary.ts
│   ├── recently_viewed.ts
│   └── tasks.ts        <- tasks overarching several sub-components
├── date_picker.ts
└── tasks.ts          <- tasks overarching several components

• If it benefits the readability and discoverability of the design, or if I consider the tasks.ts files to be too large - I split them further and create a file per task:

├── basket
│   ├── saved_for_later.ts
│   ├── summary.ts
│   ├── recently_viewed.ts
│   └── tasks             <- tasks overarching several sub-components
│       ├── AddProduct.ts
│       ├── ChangeQuantity.ts
│       ├── RemoveProduct.ts
│       └── ...
├── date_picker.ts
└── tasks.ts

• Of course, I can take that further. I might decide to separate page objects, tasks and interactions, for example:

├── basket
│   ├── saved_for_later   <- page objects, interactions, questions live in separate "packages"
│   │   ├── ui.ts
│   │   ├── interactions.ts
│   │   ├── questions.ts
│   │   └── tasks.ts
│   ├── summary.ts
│   ├── recently_viewed.ts
│   └── tasks            
│       ├── AddProduct.ts
│       ├── ChangeQuantity.ts
│       ├── RemoveProduct.ts
│       └── ...
├── date_picker.ts
└── tasks.ts

As you can see, this is an evolutionary process where the directory structure evolves together with my growing understanding of the product.

Does that help?

Jan