Simplify command line interface

[vincent-psarga]

Motivation and description of the pull request

The command-line interface is currently pretty hard to use (there's currently 61 options and filters available and hiptest-publisher --helpis pretty hard to read/understand).

Another issue is that there is in fact two/three tools built in hiptest-publisher:

• code generation
• upgrade of action words library
• pushing results back to HipTest

The idea behind this PR is to see what could be doable to make this better. I've been trying GLI to create sub-commands in order to make this simpler.
I also renamed the command line hiptest-clias we do more than publishing.

It looks like this now:

bundle exec hiptest-cli
NAME
    hiptest-cli - Translate your Hiptest examples in executable code and integrate with any CI tool

SYNOPSIS
    hiptest-cli [global options] command [command options] [arguments...]

VERSION
    0.0.1

GLOBAL OPTIONS
    -c, --config=PATH           - Config file (default: none)
    -t, --token=TOKEN           - Secret token (default: none)
    -o, --output-directory=PATH - Output directory (default: .)
    -s, --site=TOKEN            - URL of the site (default: https://hiptest.com)
    --http-proxy=PROXY_URL      - http-proxy to use (default: none)
    -x, --xml-file=PROJECT.xml  - XML file to use instead of fetching it from HipTest (default: none)
    --version                   - Display the program version
    --check-version             - Check if a more recent version exists
    --force                     - Force overwrite of any file
    -v, --verbose               - Use verbose mode
    --help                      - Show this message

COMMANDS
    help    - Shows a list of commands or help for one command
    publish - Generate executable code
    scale   - Scale your action words library
    share   - Share your test execution results on Hiptest

And each sub-command as its own parameters:

publishing

The sub-command is named publish. It still has a load of options (but I removed some like test-only, `àctionwords-onlyand leafless``which are deprecated and/or buggy).

bundle exec hiptest-cli publish --help
NAME
    publish - Generate executable code

SYNOPSIS
    hiptest-cli [global options] publish [command options] 
    hiptest-cli [global options] publish [command options] filter [--folder_ids IDS] [--folder_name NAME] [--not-recursive] [--scenario_ids IDS] [--scenario_name NAME] [--status STATUS] [--tags TAGS]

COMMAND OPTIONS
    -l, --language=LANG             - Target language (default: ruby)
    -f, --framework=FRAMEWORK       - Target framework (default: none)
    --overriden-templates=PATH      - Path to overriden templates (default: none)
    --test-run-id=ID                - ID of the test run to generate code from (default: none)
    --test-run-name=CI              - Name of the test run to generate code from (default: none)
    --filename-pattern=PATTERN      - Filename pattern (containing %s) (default: none)
    --only=CATEGORIES               - Select categories of data to export (tests, actionwords ...) (default: none)
    --without=CATEGORIES            - Select categories of data to exclude (tests, actionwords ...) (default: none)
    --library-name=LIBRARY_NAME     - Select actionword library to export (default: none)
    --sort=id,order,alpha           - Select order in which actionwords are generated (default: none)
    --parameter-delimiter=DELIMITED - Parameter delimiter (for Gherkin based export only) (default: none)
    --meta=META                     - Meta-data to use in exports (default: none)
    --keep-filenames                - Keep the same name as in HipTest for the test files (note: may cause encoding issues)
    --keep-foldernames              - Keep the same name as in HipTest for the folders (note: may cause encoding issues)
    --with-folders                  - Export with the same hierarchy than in Hiptest
    --empty-folders                 - Export folders without tests
    --split-scenarios               - Export each scenario in a separate file
    --[no-]uids                     - Export scenario UIDs in test files
    --[no-]parent-folder-tags       - Add folder tags to scenarios
    --with-dataset-names            - Export dataset name when creating feature files (note: available only for Gherkin-based exports)

COMMANDS
    <default> - 
    filter    - Filter exported data

Note: filter is a sub-command here. But the tests will be published too.

bundle exec hiptest-cli publish filter --help
NAME
    filter - Filter exported data

SYNOPSIS
    hiptest-cli [global options] publish filter [command options] 

COMMAND OPTIONS
    --folder_ids=IDS     - Filter on folder ids (use commas to separate ids when fetching multiple folders) (default: none)
    --folder_name=NAME   - Filter on folder name (only one name is accepted) (default: none)
    --scenario_ids=IDS   - Filter on scenario ids (use commas to separate ids when fetching multiple scenarios) (default: none)
    --scenario_name=NAME - Filter on scenario name (only one name is accepted) (default: none)
    --status=STATUS      - Filter on test status in last build (use in conjunction with a test run) (default: none)
    --tags=TAGS          - Filter on scenarios and folder tags (use commas to separate tags when using multiple tags) (default: none)
    --not-recursive      - Used in conjunction with filter-on-folder-ids or filter-on-folder-name: only exports those folders, not their children

upgrading action words library

The sub-command is named scalewhich is an awful name :/ Any better proposition is welcome :)

bundle exec hiptest-cli scale --help         
NAME
    scale - Scale your action words library

SYNOPSIS
    hiptest-cli [global options] scale [command options] 

COMMAND OPTIONS
    --json               - Output changes in JSON format
    --created            - Show action words created
    --deleted            - Show action words deleted
    --renamed            - Show action words renamed
    --signature-changed  - Show action words which signature changed
    --definition-changed - Show action words which definition changed
    --signature          - Update signature file

pushing results

The sub-command has been named share as --pushmay not be that self-explanatory.

bundle exec hiptest-cli share --help
NAME
    share - Share your test execution results on Hiptest

SYNOPSIS
    hiptest-cli [global options] share [command options] 

COMMAND OPTIONS
    -f, --file, --files=FILE.tap        - Test report file(s) to push (required, default: none)
    --push-format=tap                   - Format of the report file(s) (default: tap)
    --id, --test-run-id=1234            - ID of the test run where results will be shown (default: none)
    --name, --test-run-name=CI          - Name of the test run where results will be shown (default: none)
    -e, --execution-environment=ENV     - Execution environment where tests were executed (default: none)
    --global-failure-on-missing-reports - Mark tests as failed if no reports are present```

TODO

Discuss :D

Ease migration

Also one thing I'd like is to have hiptest-publisher 2.0 supporting only this new system, but the next releases in the 1.x should help users in the migration.

Something like this:

hiptest-publisher -c config-file --test-run-id=12

DEPRECATION: hiptest-publisher executable will be deprecated, use this command line instead:
hiptest-cli -c config-file publish --test-run-id=12

hiptest-publisher -c config-file --show-actionwords-diff

DEPRECATION: hiptest-publisher executable will be deprecated, use this command line instead:
hiptest-cli -c config-file scale

hiptest-publisher -c config-file --test-run-id=12 --push=report.xml --push-format=junit

DEPRECATION: hiptest-publisher executable will be deprecated, use this command line instead:
hiptest-cli -c config-file share--test-run-id=12 --format=junit --file=report.xml

Ease migration to new config file format

GLI support config files based on the interface in a Yaml format, we should have something like:

hiptest-publisher -c config-file --generate-hiptest-cli-config
site: https://hiptest.com
publish:
  language: java
  overriden_templates: "./templates"
share:
  test_run_id: 12
  push_format: junta

Find a better wording

Most of the options are not self-explanatory :/ at least the help for them should be easier to understand.

Type of change

• Breaking change (loosing support of old ruby versions, incompatibility with previous templates or config files)
• New functionnality
• Bug fix

Checklist:

• Tests have been added
• Documentation has been added

[cbliard]

remove the -cli

[cbliard]

I think that underscore and dash should not be mixed in parameters, like in --folder_ids as it breaks the rule of least surprise.

[vincent-psarga]

I think that underscore and dash should not be mixed in parameters, like in --folder_ids as it breaks the rule of least surprise.

damn copy-paste :/
but yes, you're 100% right :)

[cbliard]

suggestions:

• replace scale by actionwords:

hiptest actionwords --json               - Output changes in JSON format
hiptest actionwords --created            - Show action words created
hiptest actionwords --deleted            - Show action words deleted
hiptest actionwords --renamed            - Show action words renamed
hiptest actionwords --signature-changed  - Show action words which signature changed
hiptest actionwords --definition-changed - Show action words which definition changed
hiptest actionwords --signature          - Update signature file

or by maintain

hiptest maintain --json               - Output changes in JSON format
hiptest maintain --created            - Show action words created
hiptest maintain --deleted            - Show action words deleted
hiptest maintain --renamed            - Show action words renamed
hiptest maintain --signature-changed  - Show action words which signature changed
hiptest maintain --definition-changed - Show action words which definition changed
hiptest maintain --signature          - Update signature file

After trying it, maintain is maybe not as nice as it sounds :/

Well, we need to discuss that together...

[jbpros]

Disclaimer: I have very little context and might make irrelevant comments ;)

I think it's a great idea to revamp the CLI. My quick thoughts:

The words publish and share sound vague and redundant. We're even using the word push in the documentation of share, which looks like we're still looking for the right words.

What if all commands were first focused on objects and then on actions, following Christophe's suggestion?

$ hiptest actionwords upgrade ...
$ hiptest actionwords generate ...
$ hiptest actionwords show ...
$ hiptest test-results publish ...