@toa.io/userland 0.2.1-dev.3

package/example/components/echo/beacon/manifest.toa.yaml

@@ -0,0 +1,9 @@
+name: beacon
+namespace: echo
+
+operations:
+  signal:
+    output: string
+
+configuration:
+  signal: quack

package/example/components/echo/beacon/operations/signal.js

@@ -0,0 +1,7 @@
+'use strict'
+
+async function observation (input, none, context) {
+  return context.configuration.signal
+}
+
+exports.observation = observation

package/example/components/echo/beacon/samples/signal.yaml

@@ -0,0 +1,7 @@
+title: Should echo
+output: quack
+---
+title: Should substitute configuration
+output: woof
+configuration:
+  signal: woof

package/example/components/math/calculations/manifest.toa.yaml

@@ -0,0 +1,16 @@
+name: calculations
+namespace: math
+
+entity: null
+
+operations:
+  add:
+    input:
+      a: number
+      b: number
+    output: number
+  increment:
+    input:
+      value: number
+      times: 1
+    output: number

package/example/components/math/calculations/operations/add.js

@@ -0,0 +1,7 @@
+'use strict'
+
+async function observation (input) {
+  return input.a + input.b
+}
+
+exports.observation = observation

package/example/components/math/calculations/operations/increment.js

@@ -0,0 +1,15 @@
+'use strict'
+
+async function observation (input, none, context) {
+  let value = input.value
+
+  for (let i = 0; i < input.times; i++) {
+    const reply = await context.local.add({ input: { a: value, b: 1 } })
+
+    value = reply.output
+  }
+
+  return value
+}
+
+exports.observation = observation

package/example/components/math/calculations/samples/add.yaml

@@ -0,0 +1,11 @@
+title: Should add numbers
+input:
+  a: 1
+  b: 2
+output: 3
+---
+title: Should add negative numbers
+input:
+  a: -1
+  b: -2
+output: -3

package/example/components/math/calculations/samples/increment.yaml

@@ -0,0 +1,30 @@
+title: Should increment number
+input:
+  value: 1
+output: 2
+local:
+  add:
+    input:
+      a: 1
+      b: 1
+    output: 2
+---
+title: Should increment with actual call
+input:
+  value: 2
+output: 3
+---
+title: Should increment twice (with second actual call)
+input:
+  value: 0
+  times: 2
+output: 2
+local:
+  add:
+    - input:
+        a: 0
+        b: 1
+      output: 1
+    - input:
+        a: 1
+        b: 1

package/example/components/math/proxy/manifest.toa.yaml

@@ -0,0 +1,11 @@
+name: proxy
+namespace: math
+
+entity: null
+
+operations:
+  add:
+    input:
+      a: number
+      b: number
+    output: number

package/example/components/math/proxy/operations/add.js

@@ -0,0 +1,10 @@
+'use strict'
+
+async function observation (input, none, context) {
+  const request = { input }
+
+  // noinspection JSUnresolvedVariable
+  return context.remote.math.calculations.add(request)
+}
+
+exports.observation = observation

package/example/components/math/proxy/samples/add.yaml

@@ -0,0 +1,11 @@
+title: Should add numbers
+input:
+  a: 1
+  b: 2
+output: 3
+remote:
+  math.calculations.add:
+    input:
+      a: 1
+      b: 2
+    output: 3

package/example/components/tea/pots/manifest.toa.yaml

@@ -0,0 +1,28 @@
+name: pots
+namespace: tea
+
+entity:
+  storage: mongodb
+  schema:
+    material*: [glass, ceramic, steel]
+    volume: number
+    booked: false
+
+operations:
+  transit:
+    concurrency: none
+    input:
+      material: .
+      volume: .
+      booked: .
+  same:
+    input: .material
+    output: array
+
+receivers:
+  store.orders.created:
+    transition: transit
+    binding: amqp # avoid discovery
+
+configuration:
+  step: 0.5

package/example/components/tea/pots/operations/same.js

@@ -0,0 +1,13 @@
+'use strict'
+
+async function observation (input, none, context) {
+  const criteria = `material==${input}`
+  const query = { criteria, limit }
+
+  // noinspection JSUnresolvedFunction
+  return context.local.enumerate({ query })
+}
+
+const limit = 10
+
+exports.observation = observation

package/example/components/tea/pots/receivers/store.orders.created.js

@@ -0,0 +1,8 @@
+'use strict'
+
+const request = async (payload) => ({
+  input: { booked: true },
+  query: { id: payload.pot }
+})
+
+exports.request = request

package/example/components/tea/pots/samples/messages/store.orders.created.yaml

@@ -0,0 +1,37 @@
+title: Should book a pot
+payload:
+  pot: 1b9d7983bc204c8f8928d843a666a642
+input:
+  booked: true
+query:
+  id: 1b9d7983bc204c8f8928d843a666a642
+---
+title: Should book a pot (with request sample)
+payload:
+  pot: 1b9d7983bc204c8f8928d843a666a642
+input:
+  booked: true
+query:
+  id: 1b9d7983bc204c8f8928d843a666a642
+request:
+  current:
+    id: 1b9d7983bc204c8f8928d843a666a642
+    material: glass
+    booked: false
+  next:
+    id: 1b9d7983bc204c8f8928d843a666a642
+    material: glass
+    booked: true
+---
+title: Should book a pot (without receiver output verification)
+payload:
+  pot: 1b9d7983bc204c8f8928d843a666a642
+request:
+  current:
+    id: 1b9d7983bc204c8f8928d843a666a642
+    material: glass
+    booked: false
+  next:
+    id: 1b9d7983bc204c8f8928d843a666a642
+    material: glass
+    booked: true

package/example/components/tea/pots/samples/same.yaml

@@ -0,0 +1,8 @@
+title: Should find same material
+input: steel
+local:
+  enumerate:
+    query:
+      criteria: 'material==steel'
+      limit: 10
+    output: []

package/example/components/tea/pots/samples/transit.yaml

@@ -0,0 +1,43 @@
+title: Should create
+input:
+  material: glass
+  volume: 1.5
+next:
+  material: glass
+  volume: 1.5
+---
+title: Should update
+input:
+  material: steel
+current:
+  material: glass
+  volume: 1.5
+next:
+  material: steel
+  volume: 1.5
+---
+title: Should emit `created` event
+input:
+  material: glass
+  volume: 1.5
+next:
+  material: glass
+  volume: 1.5
+events:
+  created:
+    material: glass
+    volume: 1.5
+---
+title: Should emit `updated` event
+input:
+  material: steel
+current:
+  material: glass
+  volume: 1.5
+next:
+  material: steel
+  volume: 1.5
+events:
+  updated:
+    material: steel
+    volume: 1.5

package/example/context.toa.yaml

@@ -0,0 +1,3 @@
+name: examples
+packages: components/*/*
+registry: example

package/example/samples/math.proxy.add.yaml

@@ -0,0 +1,5 @@
+title: Should add numbers
+input:
+  a: 1
+  b: 2
+output: 3

package/example/samples/messages/store.orders.created.yaml

@@ -0,0 +1,8 @@
+title: Should book a pot
+component: tea.pots
+payload:
+  pot: a959effedd5d4c34a3ee9f640dab2d7e
+input:
+  booked: true
+query:
+  id: a959effedd5d4c34a3ee9f640dab2d7e

package/example/stage/call.test.js

@@ -0,0 +1,39 @@
+'use strict'
+
+const { resolve } = require('node:path')
+const { exceptions: { RequestContractException } } = require('@toa.io/core')
+const stage = require('@toa.io/userland/stage')
+
+const root = resolve(__dirname, '../components')
+
+/** @type {toa.core.Component} */
+let remote
+
+beforeAll(async () => {
+  const path = resolve(root, 'math/calculations')
+
+  await stage.composition([path])
+
+  remote = await stage.remote('math.calculations')
+})
+
+afterAll(async () => {
+  await stage.shutdown()
+})
+
+it('should call endpoint', async () => {
+  const a = Math.random()
+  const b = Math.random()
+
+  const reply = await remote.invoke('add', { input: { a, b } })
+
+  expect(reply.output).toStrictEqual(a + b)
+})
+
+it('should throw on invalid input', async () => {
+  const a = 'not a number'
+  const b = 'neither'
+
+  await expect(remote.invoke('add', { input: { a, b } }))
+    .rejects.toBeInstanceOf(RequestContractException)
+})

package/example/stage/events.test.js

@@ -0,0 +1,48 @@
+'use strict'
+
+const { resolve } = require('node:path')
+const stage = require('@toa.io/userland/stage')
+
+const binding = stage.binding.binding
+const root = resolve(__dirname, '../components')
+
+/** @type {toa.core.Component} */
+let remote
+
+beforeAll(async () => {
+  const path = resolve(root, 'tea/pots')
+
+  await stage.composition([path])
+
+  remote = await stage.remote('tea.pots')
+})
+
+afterAll(async () => {
+  await stage.shutdown()
+})
+
+it('should receive event', async () => {
+  const created = await remote.invoke('transit', { input: { material: 'glass' } })
+  const id = created.output.id
+  const payload = { pot: id }
+  const message = { payload }
+  const request = { query: { id } }
+
+  await binding.emit('store.orders.created', message)
+
+  const reply = await remote.invoke('observe', request)
+
+  expect(reply.output.booked).toStrictEqual(true)
+})
+
+it('should emit event', async () => {
+  expect.assertions(1)
+
+  const material = 'steel'
+
+  await binding.subscribe('tea.pots.created', (pot) => {
+    expect(pot.payload.material).toStrictEqual(material)
+  })
+
+  await remote.invoke('transit', { input: { material } })
+})

package/example/stage/invoke.test.js

@@ -0,0 +1,29 @@
+'use strict'
+
+const { resolve } = require('node:path')
+const stage = require('@toa.io/userland/stage')
+
+const root = resolve(__dirname, '../components')
+
+/** @type {toa.core.Component} */
+let component
+
+beforeAll(async () => {
+  const path = resolve(root, 'math/calculations')
+
+  component = await stage.component(path)
+})
+
+afterAll(async () => {
+  await stage.shutdown()
+})
+
+it('should invoke', async () => {
+  const a = Math.random()
+  const b = Math.random()
+
+  const reply = await component.invoke('add', { input: { a, b } })
+
+  expect(reply.exception).toBeUndefined()
+  expect(reply.output).toStrictEqual(a + b)
+})

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@toa.io/userland",
+  "version": "0.2.1-dev.3",
+  "description": "Toa development kit",
+  "homepage": "https://toa.io",
+  "author": {
+    "name": "Artem Gurtovoi",
+    "url": "https://github.com/temich"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toa-io/toa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toa-io/toa/issues"
+  },
+  "engines": {
+    "node": ">= 12.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "dependencies": {
+    "@toa.io/boot": "*",
+    "@toa.io/core": "*",
+    "@toa.io/filesystem": "*",
+    "@toa.io/generic": "*",
+    "@toa.io/norm": "*",
+    "@toa.io/schemas": "*",
+    "@toa.io/yaml": "*",
+    "tap": "16.3.4"
+  }
+}

package/readme.md

@@ -0,0 +1,9 @@
+# Toa development kit
+
+- [Stage](./stage): integration tests framework (Node.js)
+- [Samples](./samples): YAML-based declarative tests
+- Features[^1]: Gherkin steps definition ([cucumber.js](https://github.com/cucumber/cucumber-js))
+
+See [example](./example).
+
+[^1]: not yet implemented

package/samples/notes.md

@@ -0,0 +1,12 @@
+# Developer notes
+
+## Extending Replay
+
+1. Update [`example`](../example). `toa replay` should either fail or throw exception.
+2. Add [feature](./features). It should fail.
+3. If the new decorator is being developed:
+    1. Add the [decorator](/extensions/sampling/docs/replay.md).
+    2. Add [boot extension](/runtime/boot/src/extensions).
+4. Update `suite` [translation](./src/.suite/.component/translate.js).
+5. Ensure feature is passing.
+6. Ensure example is passing with `toa replay`.

package/samples/package.json

@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "main": "src/index.js",
+  "types": "types/index.d.ts"
+}

package/samples/readme.md

@@ -0,0 +1,66 @@
+# Samples
+
+## TL;DR
+
+<a href="https://miro.com/app/board/uXjVOoy0ImU=/?moveToWidget=3458764532091744292&cot=14">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="./docs/sampling-dark.jpg">
+        <img alt="4D" width="640" height="435" src="./docs/sampling-light.jpg">
+    </picture>
+</a>
+
+See [features](/features/replay).
+
+## Operation Samples
+
+Sample is an object containing values of operation inputs (i.e.: request, context outputs and
+current state) to be substituted and outcomes (reply, context calls, next state and events emission)
+to be verified. See its [schema](./src/.suite/.component/sample.cos.yaml).
+
+> Although `input` and `output` are declared as arbitrary values, they must conform to the
+> corresponding
+> operation schemas.
+
+### Declaration
+
+> Samples must be declared
+> as [multi-document YAML files](https://yaml.org/spec/1.2.2/#22-structures).
+
+Operation samples must be located under the `samples` directory in the component or context root.
+Sample file names must follow the convention: `namespace.name.operation.yaml`, that is, be an
+endpoint of the operation samples to be applied to. For component-level sample files `namespace`
+and `name` must match corresponding component, therefore are optional.
+
+## Message Samples
+
+Message Sample is an object containing receiver's input (`payload`) to be substituted and
+outcomes (`input` and `query`) to be verified. Message sample may contain corresponding operation
+sample. See its [schema](#).
+
+> Message samples are always [autonomous](#autonomy).
+
+### Declaration
+
+Operation samples must be located under the `samples/messages` directory in the component or context
+root. Samples file names must follow the convention `namesace.component.event.yaml`, that is, be a
+label
+of the event receiver is consuming.
+
+## Autonomy
+
+Component level samples are *autonomous*, namely, does not assume actual remote calls as
+replaying of component-level samples will boot only that component. Remote call attempt not declared
+within sample will cause an exception.
+See [examples](../example/components/math/calculations/samples).
+
+For context level samples (integration samples), remote calls with non-declared outputs will be
+actually performed. Replaying these samples will boot the composition with all components of the
+context (so as required extensions). See [examples](../example/samples).
+
+> Integration samples are more flexible and less sensitive to implementation details.
+
+## Replay
+
+Samples may be *replayed* using [`toa replay`](/runtime/cli/readme.md#replay) command.
+
+> Replaying samples requires local deployment environment.

package/samples/src/.replay/.suite/component.js

@@ -0,0 +1,25 @@
+'use strict'
+
+const stage = require('@toa.io/userland/stage')
+
+const { operation } = require('./operation')
+
+/**
+ *
+ * @param {string} id
+ * @param {toa.samples.operations.Set} set
+ * @param {boolean} autonomous
+ * @returns {Function}
+ */
+const component = (id, set, autonomous) =>
+  async (test) => {
+    const remote = await stage.remote(id)
+
+    for (const [endpoint, samples] of Object.entries(set)) {
+      await test.test(endpoint, operation(remote, endpoint, samples, autonomous))
+    }
+
+    await remote.disconnect()
+  }
+
+exports.component = component

package/samples/src/.replay/.suite/index.js

@@ -0,0 +1,7 @@
+'use strict'
+
+const { operations } = require('./operations')
+const { messages } = require('./messages')
+
+exports.operations = operations
+exports.messages = messages

package/samples/src/.replay/.suite/messages.js

@@ -0,0 +1,39 @@
+'use strict'
+
+const { binding } = require('@toa.io/userland/stage').binding
+
+const translate = require('./translate')
+
+/**
+ * @param {toa.samples.messages.Set} messages
+ * @param {boolean} autonomous
+ * @return {Function}
+ */
+const messages = (messages, autonomous) =>
+  async (test) => {
+    for (const [label, samples] of Object.entries(messages)) {
+      await test.test(label, message(label, samples, autonomous))
+    }
+  }
+
+/**
+ * @param {string} label
+ * @param {toa.samples.Message[]} samples
+ * @param {boolean} autonomous
+ * @returns {function}
+ */
+const message = (label, samples, autonomous) =>
+  async (test) => {
+    let n = 0
+
+    for (const sample of samples) {
+      n++
+
+      const message = translate.message(sample, autonomous)
+      const name = sample.title ?? 'Sample #' + n
+
+      await test.test(name, async () => binding.emit(label, message))
+    }
+  }
+
+exports.messages = messages

package/samples/src/.replay/.suite/operation.js

@@ -0,0 +1,28 @@
+'use strict'
+
+const translate = require('./translate')
+
+/**
+ * @param {toa.core.Component} remote
+ * @param {string} endpoint
+ * @param {toa.samples.Operation[]} samples
+ * @param {boolean} autonomous
+ * @returns {Function}
+ */
+const operation = (remote, endpoint, samples, autonomous) =>
+  async (test) => {
+    let n = 0
+
+    for (const operation of samples) {
+      n++
+
+      const request = translate.operation(operation, autonomous)
+      const name = operation.title ?? 'Sample #' + n
+
+      await test.test(name, async () => remote.invoke(endpoint, request))
+    }
+
+    test.end()
+  }
+
+exports.operation = operation