v1.7.0

✨ Test execution report in text format (experimental)

This feature is currently in experimental stage and might see bigger changes.

Testla comes with a text reporter which logs all activities in a file and gives insights about the overall test execution result.

To activate the reporter announce it in your playwright.config.ts as follows.

reporter: [
    [
        // the reporter from testla
        '@testla/screenplay-playwright/reporter/text',
        // optional: the path to the output file, defaults to: screenplay-report.txt
        { outputFile: 'results.txt' },
    ],
    // other reporters
],

✨ Print structured logs to stdout

It is now possible to print structured logs to stdout. This can be achieved as follows.

import { STRUCTURED_LOGS_ENVVAR_NAME } from '@testla/screenplay'

// activating structured logs to stdout
process.env[STRUCTURED_LOGS_ENVVAR_NAME] = 'true';

✨ Mask input values in logs

Input values can be masked in the logs via the option { maskInLogs: true } which is suggested for handling passwords or other classified information in tests.

This option has been introduced for the following web actions: Fill.in, Type.in and Press.sequentially

🐞 Module has no exported member 'Reload'

If you want to reload a page we expect the import from the web actions:
This was actual not possible because the member Reload is not exported in index.ts under web

With the new version this issue is fixed now you can use the Reload action and import it as expected.

import { Click, Element, Navigate, Reload, Wait } from '@testla/screenplay-playwright/web';

🐞 Element Question - Ability Aliasing not used

In some cases you may want to ask questions and use an ability alias to find out about the status of the system under test.
This can be achieved as follows:

await actor.asks(
    Element.toBe.visible(locator).withAbilityAlias(alias),
);

Version 1.6.0

orSkipOnFail for Actions and Tasks

You may have actions or tasks which might (expectedly) fail during the test. An example is to click an element if it is present while it is also fine to proceed with the test when the element is not available.

This can be achieved as follows:

await actor.attemptsTo(
    // this action might fail but the test will continue
    Click.on('#eventually-available').orSkipOnFail,
    Click.on('#definitely-available'),
);

failAsFalse for Questions

In some cases you may want to ask questions to find out about the status of the system under test to make decisions on how to move on with your test. In order to not fail a test but receive information about questions being answered negative you can use failAsFalse on a question which then returns a boolean value instead.

// find out if question was answered with false
const wasLoggedIn = await actors.asks(
    Login.toBe.successful().failAsFalse,
);

// proceed based on answer from above
if (wasLoggedIn === false) {
    // some code to be executed on false case
}

Version 1.5.1

Fix in documentation

An issue with the wrong install command in the documentation was fixed.

Version 1.5.0

Version 1.5.0

Logging

We added logging to provide developers with better debugging means.

To enable the logs set the DEBUG environment variable as follows:

DEBUG=testla:sp

The corresponding logging output will look like:

A detailed guide about logging can be found here.

Web Action: Download

This Action allows to click on a screen element and download a file - optionally with custom filepath and filename.

Actor.attempsTo(
    Download.file('#mySelector'),
    Download.file('#mySelector', { filepath: './downloads', filename: 'file.txt' }),
);

Web Action: Wait.forEvent

New waiting functionality to wait for an event to be propagated.

Actor.attempsTo(
    Wait.forEvent('my-event'),
);

Internal Code Optimizations

We have done some smaller internal code optimizations to ensure code maintainability.

New APIs

• Download.file('#mySelector’, { filepath: './downloads', filename: 'file.txt' } )
• Wait.forEvent('my-event’)

Version 1.4.0

Version 1.4.0

Enhancement of Ability BrowseTheWeb (including deprecations)

We have enhanced the web ability BrowseTheWeb which will enable you to write custom actions and questions easier.
Implementation details for actions/questions that come with this library are be moved into the source code of the actions/questions themselves as opposed to be held inside BrowseTheWeb. Thus all the former business logic implementations inside BrowseTheWeb are deprecated and will be removed soon.

In order to enable the business logic inside the actions/questions a new function resolveSelectorToLocator has been added to BrowseTheWeb. Together with getPage it form the fundament building custom elements.

Lazy Selector

Lazy Selectors allow you to make use of the getByRole (and similar functions) in your screen definitions. They are defined via a function which has a Playwright page as attribute. (See below)

class MyScreen {
	static STATIC_ELEMENT = ‘#myElement’;

	static LAZY_ELEMENT: LazySelector = (page) => page.getByRole(‘button’, { name: ’my button text’ });
}

Those selectors will be evaluated live during test execution time and therefore fit perfect into the given screenplay flows.

Special thanks to the @JEnglandOhalo (community member) who contributed that feature.

Type Response in API module now Generic

The type Response is now a generic which means you can now define the type of the response body way easier.

// Response Body of type Post
const postRes: Response<Post> = await actor.attemptsTo(Get.from(‘[https://my.api.com/posts/1’](https://my.api.com/posts/1%E2%80%99)));

// Response Body type undefined
const postRes: Response = await actor.attemptsTo(Get.from(‘https://my.api.com/authors/1’));

The change is backward compatible. This means it is not mandatory to define the ResponseBody type in the type definition. In case no type is provided it will fall back to unknown.

New APIs

• resolveSelectorToLocator('#mySelector’)

Deprecations

• BrowseTheWeb

Documentation updates

We have made a few smaller changes in the documentation.

Version 1.3.0

Better documentation structure

Our documentation is getting bigger and bigger and therefore a single README does not seem to be the best fit anymore. The README file is the jump page into the new documentation structure.
In the docs folder you can find the whole documentation for the testla implemenation.

Support Frame Locators

Testla 1.3.0 introduces the support for frame locators - a locator to the iframe on the page. Frame locators capture the logic sufficient to retrieve the iframe and then locate elements in that iframe.
You can access frame objects using the inFrame() API:

Element.toBe.visible('#myLocator', { hasText: 'Your content goes here.' }).inFrame('#myFrameLocator');
// or you can also chain it
Element.toBe.visible('#content', { hasText: 'MIDDLE' }).inFrame('[name="frame-top"]').inFrame('[name="frame-middle"]');

Read more at our documentation.

Ability Aliasing

It happens that there is the need to make use of the same ability but with different settings. A usecase for that could be to invoke 2 different APIs with different base URLs and authentication tokens.
The solution Testla 1.3.0 offers is Ability Aliasing. With that multiple instances of an ability can be assigned to a user at the same time.

Actor
    .can(Ability.using(SETTINGS_1))
    .can(Ability.using(SETTINGS_2)).withAlias('aliased');

Read more at our documentation.

Web Action: Count.elements

Counts screen elements which can be found via a selector.

expect(await actor.attemptsTo(Count.elements('[type="checkbox"]'))).toBe(2);

New APIs

• inFrame('#myFrameLocator')
• pressSequentially(selector: Selector, input: string, options?: SelectorOptions)
• Count.elements counts screen elements which can be found via a selector.

Deprecations

The following methods were deprecated:

• Type.in(). Please use Fill.in() instead which is much faster. Use Press.pressSequentially() only if there is a special keyboard handling on the page, and you need to press keys one-by-one.

1.2.0

New Features

• New Element questions: toHave.text and toHave.value

Fixes

• Fix for broken Locator support for different actions after playwright breaking changes

1.1.0

Features

• Web module support Playwright Locator
• New Web Action to select options from drop downs

1.0.0

Features

• Easier style for writing questions
• Added static sleep capabilities
• Added response body type 'buffer'
• Added storage and cookie handling actions
• Added response time question

0.2.0

Features

• Introduced UseApi ability, actions for http requests formats and question for response states