Containers
Handbook - Project utilities - CLI reference

This is a technical reference for the command line interface (CLI) tool se_utils_cli in Sphere Engine Containers. The tools is a wrapper for a Python package and it is globally accessible within Sphere Engine Containers projects as a command of the name se_utils_cli.

Here you will find a detailed description covering:

  • list of utilities and their functionality,
  • discussion on typical use cases,
  • usage examples.

CLI overview

Static parameters from the Python se_utils.environment and se_utils.stage module are available by environmental variables. Consistent naming allows for mapping of corresponding parameters.

$SE_CURRENT_STAGE

# se_utils.environment.path
$SE_PATH_WORKSPACE
$SE_PATH_RUNTIME
$SE_PATH_RUNTIME_DATA
$SE_PATH_FINAL_TESTS_REPORT
$SE_PATH_UNIT_TESTS_REPORT
$SE_PATH_TEST_CASES

# se_utils.environment.network
$SE_NETWORK_PORT_HTTP
$SE_NETWORK_PORT_MYSQL
$SE_NETWORK_PORT_MONGODB
$SE_NETWORK_PORT_VNC

# se_utils.stage
$SE_PATH_STAGE_INIT_STDOUT
$SE_PATH_STAGE_INIT_STDERR
$SE_PATH_STAGE_BUILD_STDOUT
$SE_PATH_STAGE_BUILD_STDERR
$SE_PATH_STAGE_RUN_STDOUT
$SE_PATH_STAGE_RUN_STDERR
$SE_PATH_STAGE_TEST_STDOUT
$SE_PATH_STAGE_TEST_STDERR

$SE_STAGE_INIT_EXIT_CODE
$SE_STAGE_INIT_SIGNAL
$SE_STAGE_BUILD_EXIT_CODE
$SE_STAGE_BUILD_SIGNAL
$SE_STAGE_RUN_EXIT_CODE
$SE_STAGE_RUN_SIGNAL
$SE_STAGE_TEST_EXIT_CODE
$SE_STAGE_TEST_SIGNAL

The following presents shortened manual of se_utils_cli CLI tool.

NAME
  se_utils_cli - Sphere Engine Containers toolkit

SYNOPSIS
  se_utils_cli [OPTIONS] <COMMAND> [ARGS...]

  <COMMAND>=evaluate|validate|convert|grade|scenario_result|stage|environment|debug_log

OPTIONS
  --help
    Print usage statement

COMMANDS
  The se_utils_cli toolkit is divided into independed tools. Each command
  is a distint tool with its own parameters. For more details refer to a
  separate dedicated manuals. For each <COMMAND> there is a separate
  se_utils_cli-<COMMAND> manual with more details and usage examples.

  Here, you can see an overview for each command.


  evaluate <EVALUATOR> [OPTIONS] [ARGS...]
    Run evaluation process. This launches a sequence action: validate, convert and grade.

    <EVALUATOR>=Evaluator|UnitTestsEvaluator|IOEvaluator

    COMMAND OPTIONS
      --help
        Print usage statement for command

      --validator XUnitValidator|IgnoreExtraWhitespacesValidator
        Set a validator

      --converter XUnitConverter|IOConverter
        Set a converter

      --grader AtLeastOneTestPassedGrader|PercentOfSolvedTestsGrader|WeightedScoreTestsGrader
        Set a grader


  validate <VALIDATOR> [OPTIONS] [ARGS...]
    Run only a validation process.

    <VALIDATOR>=XUnitValidator|IgnoreExtraWhitespacesValidator

    COMMAND OPTIONS
      --help
        Print usage statement for command


  convert <CONVERTER> [OPTIONS] [ARGS...]
    Run only a conversion process.

    <CONVERTER>=XUnitConverter|IOConverter

    COMMAND OPTIONS
      --help
        Print usage statement for command


  grade <GRADER> [OPTIONS] [ARGS...]
    Run only a grading process.

    <GRADER>=PercentOfSolvedTestsGrader|AtLeastOneTestPassedGrader|WeightedScoreTestsGrader

    COMMAND OPTIONS
      --help
        Print usage statement for command


  scenario_result <PARAM> [OPTIONS] [ARGS...]
    Get or set scenario final result parameters.

    <PARAM>=status|score|time

    COMMAND OPTIONS
      --help
        Print usage statement for command

    COMMAND ARGS
      When no arguments, then the value is returned.

        status
          Get final status
        score
          Get final score
        time
          Get final time

      Provide a value after <PARAM> to set the value:

        status [OK|FAIL|BE|RE|TLE|PE|IE]
          Set final status

        score [xxx]
          Set final score to xxx

        time [xxx]
          Set final time


  stage <NAME> <PARAM> [OPTIONS] [ARGS...]
    Access stage outcomes.

    <NAME>=init|build|run|test

    <PARAM>=stdout|stderr

    COMMAND OPTIONS
      --help
        Print usage statement for command


  environment <PARAM> [OPTIONS] [ARGS...]
    Access various constants, parameters, paths, names, URLs, and more.

    <PARAM>=remote_url

    COMMAND OPTIONS
      --help
        Print usage statement for command

    COMMAND ARGS
        remote_url <port_number>
          Get a URL address with external port number for a given internal port number.

  send_custom_webhook <PARAM> [OPTIONS] [ARGS...]
    Send a custom webhook during a scenario execution.

    COMMAND OPTIONS
      --help
        Print usage statement for command

  debug_log <MSG> [OPTIONS] [MSGS...]
    Log messages for debugging Content Manager purpose.

    <MSG> any log message

    COMMAND OPTIONS
      --help
        Print usage statement for command

    COMMAND ARGS
      If more positional arguments are provided, they are assumed to be additional
      log messages that should be written to the debug log in consecutive lines

Commands specification

In this section we present a detailed specification for all commands of the se_utils_cli tool.

Command se_utils_cli evaluate

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-evaluate - Sphere Engine Containers tool for evaluation

SYNOPSIS
  se_utils_cli evaluate <EVALUATOR> [OPTIONS] [ARGS...]

  <EVALUATOR>=Evaluator|UnitTestsEvaluator|IOEvaluator

DESCRIPTION
  Run evaluation process. This launches a sequence action: validate, convert and grade.

OPTIONS
  --help
    Print usage statement for command

  --validator XUnitValidator|IgnoreExtraWhitespacesValidator
    Set a validator

  --converter XUnitConverter|IOConverter
    Set a converter

  --grader AtLeastOneTestPassedGrader|PercentOfSolvedTestsGrader|WeightedScoreTestsGrader
    Set a grader

EXAMPLES
  • Run a default evaluation process for a project with jUnit unit tests.

    $ se_utils_cli evaluate UnitTestsEvaluator

  • Run an evaluation process for a project with jUnit unit tests (same as in first example)
    by specifying evaluation process parameters directly.

    $ se_utils_cli evaluate Evaluator --validator "XUnitValidator" \
      --converter "XUnitConverter" --grader "PercentOfSolvedTestsGrader"

Example:

#!/bin/bash

se_utils_cli evaluate Evaluator \
  --validator "XUnitValidator" \
  --converter "XUnitConverter" \
  --grader "PercentOfSolvedTestsGrader"

Resources:

Command se_utils_cli validate

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-validate - Sphere Engine Containers tool for validation

SYNOPSIS
  se_utils_cli validate <VALIDATOR> [OPTIONS] [ARGS...]

  <VALIDATOR>=XUnitValidator|IgnoreExtraWhitespacesValidator

DESCRIPTION
  Run only a validation process.

OPTIONS
  --help
    Print usage statement for command

EXAMPLES
  • Manually run a validation process that compares user output with model output
    by ignoring additional white characters.

    $ se_utils_cli validate IgnoreExtraWhitespacesValidator

Example:

#!/bin/bash

DEFAULT_USER_OUTPUT_PATH="$SE_PATH_STAGE_RUN_STDOUT"
DEFAULT_TEST_OUTPUT_PATH="$SE_PATH_TEST_CASES/0.out"

USER_OUTPUT_PATH="~/workspace/out.txt"
TEST_OUTPUT_PATH="~/workspace/.sphere-engine/out.txt"

# copy output files to the default locations
cp $USER_OUTPUT_PATH $DEFAULT_USER_OUTPUT_PATH
cp $TEST_OUTPUT_PATH $DEFAULT_TEST_OUTPUT_PATH

validation_output="$(se_utils_cli validate IgnoreExtraWhitespacesValidator)"
# here you have to interpret validation output

Resources:

Command se_utils_cli convert

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-convert - Sphere Engine Containers tool for convertion

SYNOPSIS
  se_utils_cli convert <CONVERTER> [OPTIONS] [ARGS...]

  <CONVERTER>=XUnitConverter|IOConverter

DESCRIPTION
  Run only a conversion process.

OPTIONS
  --help
    Print usage statement for command

EXAMPLES
  • Manually run a conversion process create a final tests report from the jUnit
    XML report from unit tests.

    $ se_utils_cli convert XUnitConverter

Example:

#!/bin/bash

USER_JUNIT_REPORT_PATH="~/workspace/maven_project/target/report.xml"

# copy unit tests report to the default location
cp $USER_JUNIT_REPORT_PATH $SE_PATH_UNIT_TESTS_REPORT

se_utils_cli convert XUnitConverter

Resources:

Command se_utils_cli grade

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-grade - Sphere Engine Containers tool for grading

SYNOPSIS
  se_utils_cli grade <GRADER> [OPTIONS] [ARGS...]

  <GRADER>=PercentOfSolvedTestsGrader|AtLeastOneTestPassedGrader|WeightedScoreTestsGrader

DESCRIPTION
  Run only a grading process.

OPTIONS
  --help
    Print usage statement for command

EXAMPLES
  • Manually run a grading process that accepts the final tests report as successful
    if at least one test is successful. The final score is set as a percentage of
    successful tests.

    $ se_utils_cli grade PercentOfSolvedTestsGrader

Example:

#!/bin/bash

cp '~/workspace/custom_report.json' "$SE_PATH_FINAL_TESTS_REPORT"

se_utils_cli grade AtLeastOneTestPassedGrader

Resources:

Command se_utils_cli scenario_result

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-scenario_result - Sphere Engine Containers tool for managing final results

SYNOPSIS
  se_utils_cli scenario_result <PARAM> [OPTIONS] [ARGS...]

  <PARAM>=status|score|time

DESCRIPTION
  Get or set scenario final result parameters.

OPTIONS
  --help
    Print usage statement for command

ARGS
  When no arguments, then the value is returned.

    status
      Get final status
    score
      Get final score
    time
      Get final time

  Provide a value after <PARAM> to set the value:

    status [OK|FAIL|BE|RE|TLE|PE|IE]
      Set final status

    score [xxx]
      Set final score to xxx

    time [xxx]
      Set final time

EXAMPLES
  • Set final status to FAIL.

    $ se_utils_cli scenario_result status "FAIL"

  • Get final score to variable SCORE

    $ SCORE=$(se_utils_cli scenario_result score)

Example:

#!/bin/bash

# get final status to variable
FINAL_STATUS=$(se_utils_cli scenario_result status)

# set final status to FAIL
se_utils_cli scenario_result status FAIL

Resources:

Command se_utils_cli stage

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-stage - Sphere Engine Containers tool for accessing outcome of stages

SYNOPSIS
  se_utils_cli stage <NAME> <PARAM> [OPTIONS] [ARGS...]

  <NAME>=init|build|run|test

  <PARAM>=stdout|stderr

DESCRIPTION
  Access stage outcomes.

OPTIONS
  --help
    Print usage statement for command

EXAMPLES
  • Print standard error data (stderr) generate during build stage.

    $ se_utils_cli stage build stderr

Some parameters from Python module se_utils.stage are static values that are straightforward available by environmental variables.

# se_utils.stage
$SE_PATH_STAGE_INIT_STDOUT     # path to the stdout from INIT stage
                               #  default: /sphere-engine/runtime/stdout_init
$SE_PATH_STAGE_INIT_STDERR     # path to the stderr from INIT stage
                               #  default: /sphere-engine/runtime/stderr_init
$SE_PATH_STAGE_BUILD_STDOUT    # path to the stdout from BUILD stage
                               #  default: /sphere-engine/runtime/stdout_build
$SE_PATH_STAGE_BUILD_STDERR    # path to the stderr from BUILD stage
                               #  default: /sphere-engine/runtime/stderr_build
$SE_PATH_STAGE_RUN_STDOUT      # path to the stdout from RUN stage
                               #  default: /sphere-engine/runtime/stdout_run
$SE_PATH_STAGE_RUN_STDERR      # path to the stderr from RUN stage
                               #  default: /sphere-engine/runtime/stderr_run
$SE_PATH_STAGE_TEST_STDOUT     # path to the stdout from TEST stage
                               #  default: /sphere-engine/runtime/stdout_test
$SE_PATH_STAGE_TEST_STDERR     # path to the stderr from TEST stage
                               #  default: /sphere-engine/runtime/stderr_test

$SE_STAGE_INIT_EXIT_CODE       # exit code returned by the INIT stage command
$SE_STAGE_INIT_SIGNAL          # code of a signal that stopped the INIT stage command
$SE_STAGE_BUILD_EXIT_CODE       # exit code returned by the BUILD stage command
$SE_STAGE_BUILD_SIGNAL          # code of a signal that stopped the BUILD stage command
$SE_STAGE_RUN_EXIT_CODE       # exit code returned by the RUN stage command
$SE_STAGE_RUN_SIGNAL          # code of a signal that stopped the RUN stage command
$SE_STAGE_TEST_EXIT_CODE       # exit code returned by the TEST stage command
$SE_STAGE_TEST_SIGNAL          # code of a signal that stopped the TEST stage command

Example:

#!/bin/bash

if [ grep "Hello Sphere Engine Containers!" "$SE_PATH_STAGE_RUN_STDOUT" ]; then
  se_utils_cli scenario_result status "OK"
else
  se_utils_cli scenario_result status "FAIL"
fi

Resources:

Command se_utils_cli environment

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-environment - Sphere Engine Containers tool for accessing various constants
    parameters, paths, names, URLs, and more

SYNOPSIS
  se_utils_cli environment <PARAM> [OPTIONS] [ARGS...]

  <PARAM>=remote_url

DESCRIPTION
  Access various constants, parameters, paths, names, URLs, and more.

OPTIONS
  --help
    Print usage statement for command

ARGS
  remote_url <port_number>
    Get a URL address with external port number for a given internal port number.

EXAMPLES
  • Get external URL for a service running on internal post 8080.

    $ se_utils_cli environment remote_url 8080

Some parameters from Python module se_utils.environment are static values that are straightforward available by environmental variables. They are not directly associated with the se_utils_cli tool, but they are semantically connected with se_utils_cli environment command.

# se_utils.environment
$SE_CURRENT_STAGE              # name of current stage

# se_utils.environment.path
$SE_PATH_WORKSPACE             # path to the user workspace directory
                               #  default: /home/user/workspace
$SE_PATH_RUNTIME               # path to the Sphere Engine run-time directory
                               #  default: /sphere-engine/runtime
$SE_PATH_RUNTIME_DATA          # path to the Sphere Engine run-time data directory
                               #  default: /sphere-engine/runtime_data
$SE_PATH_FINAL_TESTS_REPORT    # path to the file with the final tests report
                               #  default: /sphere-engine/runtime/report.json
$SE_PATH_UNIT_TESTS_REPORT     # path to the default place for unit tests report
                               #  default: /sphere-engine/runtime/report.xml
$SE_PATH_TEST_CASES            # path to the default directory for IO tests
                               #  default: /home/user/workspace/.sphere-engine/test-cases

# se_utils.environment.network
$SE_NETWORK_PORT_HTTP          # default port for the build-in HTTP server
$SE_NETWORK_PORT_MYSQL         # default port for the build-in MySQL database server
$SE_NETWORK_PORT_MONGODB       # default port for the build-in MongoDB database server
$SE_NETWORK_PORT_VNC           # default port for the build-in VNC remote desktop server

Example:

#!/bin/bash

PROJECT_WEBSITE_URL=$(se_utils_cli environment remote_url 8080)

cp "~/workspace/ut_report.xml" $SE_PATH_UNIT_TESTS_REPORT

Resources:

Command se_utils_cli send_custom_webhook

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-send_custom_webhook - Sphere Engine Containers tool providing
    facilities for sending custom webhooks during the scenario execution.

SYNOPSIS
  se_utils_cli send_custom_webhook

DESCRIPTION
  Sends a webhook message.

OPTIONS
  --help
    Print usage statement for command

EXAMPLES
  • Send a webhook.

    $ se_utils_cli send_custom_webhook

Example:

#!/bin/bash

se_utils_cli send_custom_webhook

Resources:

Command se_utils_cli debug_log

If you are looking for a Python equivalent of this command, please go here.

NAME
  se_utils_cli-debug_log - Sphere Engine Containers tool providing facilities
    and shorthands for debugging procedures.

SYNOPSIS
  se_utils_cli debug_log <MSG> [OPTIONS] [MSGS...]

  <MSG> is any log message

DESCRIPTION
  Log messages for debugging Content Manager purpose.

OPTIONS
  --help
    Print usage statement for command

ARGS
  If more positional arguments are provided, they are assumed to be additional
  log messages that should be written to the debug log in consecutive lines

EXAMPLES
  • Log a single message to the debug stream.

    $ se_utils_cli debug_log "Sphere Engine is AMAZING!"

  • Log three messages to the debug stream.

    $ se_utils_cli debug_log "This" "works" "great!"

  • Print the content of a file to the debug stream.

    $ se_utils_cli debug_log < /home/user/workspace/my_log.txt

Example:

#!/bin/bash

se_utils_cli debug_log "this is an internal note for Content Manager access only"
se_utils_cli debug_log < "~/workspace/my_file.txt"

Resources:

Command se_utils_cli event

SYNOPSIS
  se_utils_cli event <EVENT_NAME> [PARAM1] ... [PARAMX]

  <EVENT_NAME> is a name of the event; available events: fileContent

DESCRIPTION
  Send an event to JavaScript SDK

EXAMPLES
  • Send the fileContent event with the content of a file located at file_path.

    $ se_utils_cli event fileContent file_path

Example:

#!/bin/bash

se_utils_cli event fileContent "my_file.txt"

Resources:

  Contents