How to Serenity.js & AsciiDoc as alternative to Cucumber with instant LivingDoc 😉

[qwertysk]

Hi guys,

what do you think about idea to have Actor also as chainable tagged template literal?

This can result to type safe executable DSL (without Cucumber regex step definitions) with instant Living Documentation preview ...

Pls, how to achieve this?

@jan-molak would that be a benefit for serenity.js core (pls see zip with prototype at the end)?

Regards,
Stefan

Hints to reproduce results:
0. Extract serentity-prototype.zip and open it in VS Code

1. Then install AsciiDoc extension
2. customize .asciidoctorconfig.adoc
3. and extent it with preprocessor.js
4. Switch language mode from Typescript to AsciiDoc
5. open AsciiDoc preview
6. trust to preprocessor.js and reopen AsciiDoc preview

[jan-molak]

Hi @qwertysk

I like the AsciiDoc output, thanks for sharing your idea!

I think expressing test scenarios in a type-safe way using string templates might be quite tricky. I'm also not sure if this authoring model could allow for code completion like you have with Cucumber Gherkin files, or regular JavaScript or TypeScript.

To help me understand your idea better, what's the main benefit or expressing a test scenario like this:

////
import { test }                           from '@serenity-js/playwright-test'
import { Ensure, contain }                from '@serenity-js/assertions'
import { Goto, EnterAndConfirm, Address}  from './someImpl'
////


test('Entry without permissions is denied', async ({ Actor, Entry }) => { await Actor `

. ${Goto} the entrance of the System ${{Address: 'sys.tem'}} ``

. ${EnterAndConfirm} invalid permissions for ${Entry}

    ${{
      Name:     'KO',
      Password: 'attempt',
      action:   'Sign in'
    }} ``

. ${Ensure} that the denial of ${Entry} ${contain} reason and possible (re)actions
  
    ${{
      Error:    'Invalid permissions',
      actions:  ['Register', 'Reset password', 'Sign in']
    }} ``

`
});

Instead of using code, for example:

test('Entry without permissions is denied', async ({ actor }) => {
  await actor.attemptsTo(
    Navigate.to('https://my-system.com'),
    Login.using({
      name: 'KO',
      password: 'attempt',
      action: 'Sign in',
    }),
    Ensure.that(Login.error(), equals({
      error: 'Invalid permissions',
      actions: ['Register', 'Reset password', 'Sign in']
    }),
  );
);

If you like AsciiDoc output, have you considered writing a custom reporter? Or are you looking for enabling a different authoring experience?

[qwertysk]

Hi @jan-molak

I think that main benefits expressing a test scenario like this are:

• 3 in1 => Analysis & Test & LivingDoc in one specificatication as a CODE
• you can freely MIX code with documentation (this is different than mix code with comments only)
• printable documentation BEFORE test execution
• you have AD HOC step/specification/documentation (this is something different than step in report which has strong "template")
• you have full ARSENAL of AsciiDoc (formatting, includes, attribute substitutions, conditional processing, tables, footnotes, ....) or Markdown if you want

[jan-molak]

Cool, thanks for taking the time to explain! I think it's worth an experiment, and you seem to have a good idea of how you'd like it to work.

It feels like you could build the functionality you describe on top of what Serenity/JS already provides, and perhaps using one of the project templates as a starting point?

If there's enough interest from the Serenity/JS community, we could then bring your prototype into the main Serenity/JS project. What do you think?

[qwertysk]

@jan-molak thank you for your interest and help. I am just a beginner in Serenity, Playwright and Typescript. Unfortunately, I don't know how to build this functionality, that's why I asked how to achieve something similar.

For now, it looks like we won't move on until the idea I sent is interesting and valuable enough for someone to be able to move the prototype further ...

[jan-molak]

Hey, we all start as beginners ☺️ I'd suggest that a good way to experiment with your idea is to create a new github repository based on the Serenity/JS template for Playwright Test and try to connect the dots between what's there and AsciiDoc. If you have questions about Serenity/JS or want to bounce ideas off the community you can always ask here or join the Serenity/JS Community Chat