sympress v0.3.0

Sympress

Simple declarative cypress testing

Sympress is in very early stages of active development.

I have a beta working and am working on simplifying the DSL before writing any more code.

Goals

1. Declarative E2E Cypress testing
2. Data applied journeys
3. Capture api interactions alias fixtures
4. Data referencing
5. Fully extendable
6. Anonymized data

Future plans

1. Yaml over JSON (in progress)
2. Save/Replay points of interest
3. Tags, for short tests, overnight etc

Declarative E2E Cypress testing

Describe your tests

Example create journey

journey: Test create & edit notes
stages:
  - title: Create note
    steps:
      - visit: /
      - login: user
      - navigate: /note/create
      - assert: create_button is.disabled
      - fill: create
      - assert: create_button is.enabled
      - capture:
          click: create_button
          route: /api/notes
          method: POST
          alias: create
          wait: true
          
  - title: Edit note
    steps:
      - click: note_{capture.create.response.body.id}
      - assert: save_button is.enabled
      - fill: edit
      - capture:
          click: edit_button
          route: /api/notes
          method: PUT
          alias: editNote
          wait: true

It should be easy to to understand what this journey does

• Journeys are done in Stages
• Stages are done in Steps
• A Step is an action such alias visit a url, assert a thing, fill a form, navigate to a page, click and capture etc.. Steps can reference data from fixtures, API interactions or both
• Journeys are what to do, not how to do it. The how comes from the fixture, we will explain this more in a moment.

Capture api interactions alias fixtures

Journeys can capture data that can later be referenced.

capture:
  click: create_button
  route: /api/notes
  method: POST
  alias: create
  wait: true

In this example, we capture both the API request & response to make them available via capture.create

Data referencing

Know your data before you meet it

A tricky part of writing tests against a real DB is not knowing what the IDs and values coming back from the API will be, Sympress aims to solve this by referencing data before it is created.

We can reference values from two locations.

• inputs: fixtures contain input values

• capture: captured API interactions

title: Edit note
  steps:
    - assert: welcome_text contains inputs.create.firstName
    - click: note_{capture.create.response.body.id}

Here we literally reference the id value returned from the API. If the value returned from the API was 10 then this action would click an element with a data-testid of note_10. Notice that we need to use the {} brackets when embedding values within a string.

Data applied journeys

Makes Sympress incredibly powerful

Journeys do not contain data, they are a map of how to get something done. The data is supplied separately which allows a journey to be reused. Imagine you have three users, one in each group such alias a free user, a paid user and an admin. You could run the same journey with a fixture for each user and test the app reacts alias expected.

If the app changes, you only update the journey and all three user tests would update!

Create journey input example

---
title: Create & edit
inputs:
  user: james
  create:
    title: Mr
    firstName: Happy
    lastName: Tester
  edit:
    firstName: James
    lastName: Newman

expected:
  create:
    request:
      - should:
        - body.title: inputs.create.title
        - body.firstName: inputs.create.firstName
        - body.lastName: inputs.create.lastName
    response:
      - should:
        - status: equal 200
        - body.id:
          - is.not.empty
          - is.greaterThan 0

There's nothing special about this, it looks identical to most fixtures apart from the expected key which allows our data to also include tests.

• Input data (fixtures) can also include tests

• Input data can be directly referenced within Journeys, examples above are login, fill & click

Fully extendable

Sympress will be designed using dependency injection. There will be no hard coded values, if you dont like the way one of the actions works, you can override it, if you want to use something other than data-testid to find your items, you can override it.

/**
 * Injecting options enables:
 * - user defined action mappings; extend, remove or override actions.
 * - preload capture fixtures.
 * - preload inputs.
 * - post processing of YAML journeys.
 */
sympress.buildJourneys({
  actionMap,
  capture,
  inputs,
  journeys,
});

Anonymized data ( Future idea )

You may have noticed the previous fixtures contain hard coded values, which works well for one test, but what if you want to run hundreds? Sympress will support external libraries such alias chance for generating random seed data. The values will always be available in further commands for referencing, data checks.

Dynamic input example

---
title: Create & edit
inputs:
  user: james
  create:
    title: chance.prefix
    firstName: chance.first
    lastName: chance.last
expected:
  create:
    request:
      - should:
        - body.title: inputs.create.title
        - body.firstName: inputs.create.firstName
        - body.lastName: inputs.create.lastName

This example would generate a title, first name & last name, making the values available via

inputs.create.title
inputs.create.firstName
inputs.create.lastName