Skip to content

Add stand-alone example resources #324

Closed
@cdavernas

Description

@cdavernas
Member

What would you like to be added:

Stand-alone example json/yaml files, instead of just embedding them into an MD file

Why is this needed:

Allows SDKs and other implementations to unit test the successfull parsing of official, up-to-date examples

Other thoughts:

Now, what would be really awesome IMHO is to use factual examples, instead of theoretical ones, so that runtime implementations can test them to. The idea is to create some out-of-the-box examples for which runtime can be validated/tested.

We could use Swagger's Pet Store Api for demonstrating OpenApi function calls, and something like a free webhook tool for testing events.


What do you guys think?

Activity

self-assigned this
on Mar 31, 2021
tsurdilo

tsurdilo commented on Mar 31, 2021

@tsurdilo
Contributor

@neuroglia I was actually working on this hehe :)
I just wish there was a way to embed the files into the examples.md so we don't have to maintain both sides...

tsurdilo

tsurdilo commented on Mar 31, 2021

@tsurdilo
Contributor

@neuroglia do you think doing this for the comparison examples: https://github.com/serverlessworkflow/specification/tree/main/comparisons

would be beneficial as well?

cdavernas

cdavernas commented on Mar 31, 2021

@cdavernas
MemberAuthor

@tsurdilo Niiiice x)
Ah yes, I hear you: I face the exact same problem in some private repos. The only "sane(ish)" way to do so, IMO, is by using a pipeline to replace values in your MD with the contents of the examples. Less user-friendly to write, but at least it's up to date.

tsurdilo

tsurdilo commented on Mar 31, 2021

@tsurdilo
Contributor

@neuroglia we can host all OpenApi defs on serverlessworkflow.io ;)
+100 for "running" examples
Those can also become the start of our TCK tests as well.

cdavernas

cdavernas commented on Mar 31, 2021

@cdavernas
MemberAuthor

@neuroglia do you think doing this for the comparison examples: https://github.com/serverlessworkflow/specification/tree/main/comparisons
would be beneficial as well?

@tsurdilo I'm not sure. I must say I only did go once or twice on that specific page, as there was no need to sell me the spec further x) But I can see the added value for more analytical brains than mine I guess!

tsurdilo

tsurdilo commented on Mar 31, 2021

@tsurdilo
Contributor

@neuroglia if it helps, we do have (i hope all) examples here: https://github.com/serverlessworkflow/sdk-java/tree/main/api/src/test/resources/examples

but the problem with that is its a pain to maintain them all the time so they might not be all up to date with the spec examples, but the workflow dsl used there is validated against v0.6. Hope this helps for now until we work on this

tsurdilo

tsurdilo commented on Mar 31, 2021

@tsurdilo
Contributor

@neuroglia here are some examples the java sdk uses for validation of some certain edge cases: https://github.com/serverlessworkflow/sdk-java/tree/main/api/src/test/resources/features
hope this helps for now too :)

cdavernas

cdavernas commented on Mar 31, 2021

@cdavernas
MemberAuthor

@tsurdilo Aaaaah! Awesome! I'll use that to add some unit test before the commit that adds the reader/writer!

tsurdilo

tsurdilo commented on Mar 31, 2021

@tsurdilo
Contributor

@neuroglia one more thing, we have our dsl schemas also exposed on the website: https://serverlessworkflow.io/schemas/latest/workflow.json
this is used by the vscode plugin and the diagram generation project as well
the "latest" always points to the latest release of the spec
you can use "previous" to access v0.5 and "snapshot" to access the latest (main branch)

..maybe we should expose the examples as well there....hmmm

tsurdilo

tsurdilo commented on Apr 21, 2021

@tsurdilo
Contributor

@neuroglia
looking at this tool to possible be able to do this: https://github.com/temporalio/snipsync

github-actions

github-actions commented on Jun 6, 2021

@github-actions

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

66 remaining items

modified the milestones: v0.9, v1.0-alpha on May 25, 2023
github-actions

github-actions commented on Jul 10, 2023

@github-actions

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

github-actions

github-actions commented on Aug 25, 2023

@github-actions

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

cdavernas

cdavernas commented on May 17, 2024

@cdavernas
MemberAuthor

This has been addressed in 1.0.0, and is closed as part of #843

In 1.0.0, we did even better than what was suggested by adding a list of Gherkin features for conformance testing and Behavior Driven Development.

Example:

Feature: Flow Directive
  As an implementer of the workflow DSL
  I want to ensure that tasks are executed in the correct order
  So that my implementation conforms to the expected behavior

  Scenario: Implicit Sequence Flow
    Given a workflow with definition:
    """yaml
    document:
      dsl: 0.10
      namespace: default
      name: implicit-sequence
    do:
      setRed:
        set:
          colors: '${ .colors + [ "red" ] }'
      setGreen:
        set:
          colors: '${ .colors + [ "green" ] }'
      setBlue:
        set:
          colors: '${ .colors + [ "blue" ] }'
    """
    When the workflow is executed
    Then the workflow should complete with output:
    """yaml
    colors: [ red, green, blue ]
    """
    And setRed should run first
    And setGreen should run after setRed
    And setBlue should run after setGreen
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area: specChanges in the Specification

Type

No type

Projects

Status

Done

Relationships

None yet

    Development

    No branches or pull requests

      Participants

      @tsurdilo@ricardozanini@lsytj0413@cdavernas

      Issue actions

        Add stand-alone example resources · Issue #324 · serverlessworkflow/specification