feat: improve help message for `new` command #320

lakshz · 2022-07-11T17:07:59Z

Description

Improved the help message of 'new' command with examples

Related issue(s)

Fixes #162

github-actions

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

derberg · 2022-07-12T13:48:56Z

src/commands/new.ts

@@ -15,14 +15,22 @@ export default class New extends Command {
 static flags = {
 help: Flags.help({ char: 'h' }),
 'file-name': Flags.string({ char: 'n', description: 'name of the file' }),
- example: Flags.string({ char: 'e', description: 'name of the example to use' }),
+ example: Flags.string({ char: 'e', description: `name of the example to use. Available examples are: \n\t- default-example.yml \n\t- somethingElseWithSpecificProtocol.json (MQTT)` }),


hey, sorry, I was not super clear in related github issue.

The point here is that there are multiple different examples, and user of CLI has no idea about them. In my issue I just wanted to indicate how list of examples was suppose to look like. But in fact, list is much larger and should be built in a dynamic way in the help, not hardcoded.

when you run npm run build you will notice that in /assets/examples directory there is much more. And there is a file called examples.json. We already read this file -> https:/asyncapi/cli/pull/320/files#diff-bddcbb9edc64eedc14d10908f9c6a72353ea7a0cea813b34edc6d163f2a33f92R76 so we can list examples in the interactive mode of asyncapi new. Anyway, we should definitely use it to list all the examples in the help, so folks know what they can actually use.

I hope it makes sense 😄

Okay, got it, thanks. Working on it.

lakshz · 2022-07-14T22:35:58Z

src/commands/new.ts

@@ -24,6 +46,10 @@ export default class New extends Command {
 static args = []

 async run() {
+ const exampleDescription = await getExamplesFlagDescription();
+ this.flags.example = Flags.string({ char: 'e', description: exampleDescription});


Okay, so it's been a while now that I'm stuck on this.
The problem that I'm facing is that I fetched the example.json, mapped it, and made the description out of it. But, how do I add to my static flags?
I've tried to add it inside the run() function, before parsing the New class, but it's not working.

I think flag building doesn't like async/await and promises 😄

when I quickly play with your code:

replace any async/await with normal functions and switch to readFileSync

fix building description like this:
let description = 'name of the example to use. Available examples are:'; for (const element of examples) { description += (`\n\t - ${element.value}`); }

it works as expected:

full code:

function loadExampleFile() : Example[] { const exampleFiles = readFileSync(resolve(__dirname, '../../assets/examples/examples.json'), { encoding: 'utf8' }); //console.log(JSON.parse(exampleFiles)); return JSON.parse(exampleFiles); } function getExamplesFlagDescription() : string { const examples = loadExampleFile(); let description = 'name of the example to use. Available examples are:'; for (const element of examples) { description += (`\n\t - ${element.value}`); } return description; }

example: Flags.string({ char: 'e', description: getExamplesFlagDescription()}),

Got it, thanks a lot

derberg · 2022-07-21T08:48:39Z

@LakshyaSatpal looking good man! Please just add a unit test that validates if list of examples is rendered? I'm just pretty sure that in few months someone will say "why do we use sync function here, lemme refactor" 😆

in the test, please do not "hardcode" list of examples as the tests will be affected by changes in examples list. So in test also read examples dynamically

lakshz · 2022-07-29T10:32:01Z

Hi @derberg !
I was going through oclif documentation for testing for commands. I'm finding it challenging to write a test to check if a file is rendered.
I mean, I couldn't get what do I have to actually test, validate if the user entered the correct example name from available examples? or only check the working of loadExampleFile synchronous function that we wrote?
Btw, this is the first time I am writing unit tests. Please bear with me 😅

derberg · 2022-07-29T10:53:10Z

@LakshyaSatpal no worries. Happy to help you if you need.

you need to provide test for new functionality. New functionality is: much better help message with list of examples. We need to have a test, that will evaluate if the list of examples from /assets/examples is included in the help message that you just created.
have a look on existing tests https:/asyncapi/cli/tree/master/test/commands for commands. See how we check if certain message appears in the console

I recommend, especially if it is your first time, first create a test, where you basically hardcode the expected message in the text, so you check if the message printed in terminal match the message that you hardcode in test (with list of examples).

Once ☝🏼 works, then work on making sure that the list of examples is not hardcoded, but you read in dynamically inside the test, from examples dir

lakshz · 2022-07-29T13:51:08Z

@derberg I wrote this simple test in the new.test.ts file where I checked for help message to contain the first example which I hard coded.

test
		.stdout()
		.command(['new', '--help'])
		.it('help includes available examples', (ctx, done) => {
			expect(ctx.stdout).to.contain('- simple.yml');
			done();
		});

This shows me an error of AssertionError: expected '' to include '- simple.yml'. I believe, it is not getting that I'm checking for help flag command. Am I moving in the right direction?

sonarcloud · 2022-07-31T05:16:02Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

Souvikns · 2022-08-02T10:42:44Z

test/commands/new.test.ts

+
+ test
+ .stdout()
+ .command(['new', '-h'])


Suggested change

.command(['new', '-h'])

.command(['new', '--help'])

try doing this

Yes, I tried, getting the same error

Yeah, not working only in the test environment 🤔

found this though oclif/oclif#142 (comment)

the reason is that actually new --help in test is not successful and throws:

TypeError: cmd._help is not a function

I get the same when I try bin/run new -h with CLI. But bin/run new --help works fine when I try your branch 🤔

@Souvikns maybe we should just resign from tests in this PR and write an issue about what I described above and get that solved first. Thoughts?

ok, we need to go forward here:
@LakshyaSatpal please look at other comments, address them, and remove the test. There is no way to make it run now. The main functionality will have to stay untested 😄

also please add "additionalHelpFlags": ["-h"], to oclif configuration in package.json (line 97) so we at least make -h to work too.

Yeah, let's not add tests in this PR, but open an issue about how we cannot test the help messages. And once oclif fixes it we can add help tests for all other commands.

derberg · 2022-08-16T12:43:37Z

@LakshyaSatpal hey, you need a hand? I was out on holidays, but now back 💪🏼

lakshz · 2022-08-21T12:41:28Z

@LakshyaSatpal hey, you need a hand? I was out on holidays, but now back 💪🏼

Hi @derberg, still stuck now the same problem - not able to write a test with help flag 😥, discussed it with @Souvikns as well

derberg · 2022-11-21T15:28:20Z

src/commands/new.ts

 studio: Flags.boolean({ char: 's', description: 'open in Studio' }),
 port: Flags.integer({ char: 'p', description: 'port in which to start Studio' }),
 'no-tty': Flags.boolean({ description: 'do not use an interactive terminal' }),
 };

 static args = [];

+ static examples = [
+ 'asyncapi new\t - start creation of a file in interactive mode',
+ 'asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty\t - create new file with specific name, using one of examples and without interactive emode'


Suggested change

'asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty\t - create new file with specific name, using one of examples and without interactive emode'

'asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty\t - create a new file with a specific name, using one of the examples and without interactive mode'

derberg · 2022-11-21T16:19:37Z

test/commands/new.test.ts

+
+ test
+ .stdout()
+ .command(['new', '-h'])


ok, we need to go forward here:
@LakshyaSatpal please look at other comments, address them, and remove the test. There is no way to make it run now. The main functionality will have to stay untested 😄

also please add "additionalHelpFlags": ["-h"], to oclif configuration in package.json (line 97) so we at least make -h to work too.

derberg · 2022-12-08T10:29:39Z

@LakshyaSatpal I hope you are still interested with this one. It helps with DX and as you see it is ok that we drop testing part

…-API-cli into improve-new-help-msg

derberg

looks great from my point of view. Tried locally and works like a charm

(improve-new-help-msg)$ bin/run new -h
Creates a new asyncapi file

USAGE
  $ asyncapi new [-h] [-n <value>] [-e <value>] [-s] [-p <value>] [--no-tty]

FLAGS
  -e, --example=<value>
      name of the example to use. Available examples are:
        - simple.yml
        - anyof.yml
        - application-headers.yml
        - correlation-id.yml
        - websocket-gemini.yml
        - gitter-streaming.yml
        - mercure.yml
        - not.yml
        - operation-security.yml
        - oneof.yml
        - rpc-client.yml
        - rpc-server.yml
        - slack-rtm.yml
        - tutorial.yml
        - streetlights-kafka.yml
        - streetlights-operation-security.yml
        - streetlights-mqtt.yml

  -h, --help
      Show CLI help.

  -n, --file-name=<value>
      name of the file

  -p, --port=<value>
      port in which to start Studio

  -s, --studio
      open in Studio

  --no-tty
      do not use an interactive terminal

DESCRIPTION
  Creates a new asyncapi file

EXAMPLES
  $ asyncapi new         - start creation of a file in interactive mode

  $ asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty      - create a new file with a specific name, using one of the examples and without interactive mode

@Souvikns wanna have a look?

derberg · 2022-12-15T09:03:35Z

@Souvikns ping 😉

Souvikns

LGTM! just need to fix lint

derberg · 2022-12-20T13:27:55Z

@LakshyaSatpal hay can you fix linter issues please

…-API-cli into improve-new-help-msg

sonarcloud · 2022-12-21T20:13:07Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

sonarcloud · 2023-02-06T16:15:13Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

derberg · 2023-02-06T16:17:08Z

I have no idea why tests are failing 😭
it is not random, it is always [ERR_INVALID_ARG_TYPE]: The "warning" argument must be of type string or an instance of Error. Received an instance of TypeError but why.......#$%

@LakshyaSatpal maybe you could switch to readFile that is already used in the same file, instead of importing readFileSync? or was sync selected because description: await getExamplesFlagDescription() was not possible?

derberg · 2023-03-27T09:26:05Z

@LakshyaSatpal not sure why but you are having a lot of linter issues. Do you want to continue with this PR?

sonarcloud · 2023-04-04T14:03:42Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

derberg · 2023-04-24T13:23:39Z

@LakshyaSatpal can you specify if you plan to continue with this one, or should that be released to other contributors?

derberg · 2023-07-19T11:33:36Z

no reaction so closing, hope someone will pick it up from #162

derberg · 2023-09-04T13:31:01Z

done with #758

lakshz added 2 commits July 11, 2022 19:52

improved help message of new command

a91beb4

added examples in help message

2b2207b

lakshz requested review from Souvikns, magicmatatjahu, derberg, boyney123 and asyncapi-bot-eve as code owners July 11, 2022 17:08

github-actions bot reviewed Jul 11, 2022

View reviewed changes

lakshz changed the title ~~fix: Improved help message of 'new' command~~ fix: improved help message of 'new' command Jul 11, 2022

derberg reviewed Jul 12, 2022

View reviewed changes

lakshz added 2 commits July 15, 2022 03:59

fetched example.json

dfa4032

removed unused imports

76a254c

lakshz commented Jul 14, 2022

View reviewed changes

lakshz requested a review from derberg July 14, 2022 22:36

fetched examples.json using readFileSync

a9bab6c

added unit for help message

c4952fe

Souvikns reviewed Aug 2, 2022

View reviewed changes

Merge branch 'master' into improve-new-help-msg

af1bbee

derberg changed the title ~~fix: improved help message of 'new' command~~ fix: improve help message for new command Nov 21, 2022

derberg reviewed Nov 21, 2022

View reviewed changes

lakshz added 2 commits December 8, 2022 19:21

removed test, resolved feedbacks

1012bdd

Merge branch 'improve-new-help-msg' of github.com:LakshyaSatpal/Async…

92f97a6

…-API-cli into improve-new-help-msg

lakshz requested a review from derberg December 8, 2022 14:01

Merge branch 'master' into improve-new-help-msg

7f80e4a

derberg changed the title ~~fix: improve help message for new command~~ feat: improve help message for new command Dec 12, 2022

derberg previously approved these changes Dec 12, 2022

View reviewed changes

Souvikns previously approved these changes Dec 15, 2022

View reviewed changes

Merge branch 'master' into improve-new-help-msg

80ba9eb

lakshz added 2 commits December 22, 2022 01:38

fixed linter issues

18dc7fd

Merge branch 'improve-new-help-msg' of github.com:LakshyaSatpal/Async…

022cfbf

…-API-cli into improve-new-help-msg

lakshz dismissed stale reviews from Souvikns and derberg via 022cfbf December 21, 2022 20:12

lakshz requested a review from derberg December 21, 2022 20:13

Merge branch 'master' into improve-new-help-msg

68bd9e4

derberg closed this Feb 6, 2023

derberg reopened this Feb 6, 2023

derberg added 2 commits February 6, 2023 16:54

Merge branch 'master' into improve-new-help-msg

ad3d38d

Merge branch 'master' into improve-new-help-msg

875687b

Merge branch 'master' into improve-new-help-msg

6a7295a

Merge branch 'master' into improve-new-help-msg

640bcd2

derberg mentioned this pull request Jul 19, 2023

Improve help message with list of available examples #162

Closed

derberg closed this Jul 19, 2023

	'asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty\t - create new file with specific name, using one of examples and without interactive emode'
	'asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty\t - create a new file with a specific name, using one of the examples and without interactive mode'

feat: improve help message for new command #320

feat: improve help message for new command #320

Conversation

lakshz commented Jul 11, 2022

github-actions bot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lakshz Jul 12, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

derberg commented Jul 21, 2022

lakshz commented Jul 29, 2022 • edited Loading

derberg commented Jul 29, 2022

lakshz commented Jul 29, 2022 • edited Loading

sonarcloud bot commented Jul 31, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

derberg commented Aug 16, 2022

lakshz commented Aug 21, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

derberg commented Dec 8, 2022

derberg left a comment

Choose a reason for hiding this comment

derberg commented Dec 15, 2022

Souvikns left a comment

Choose a reason for hiding this comment

derberg commented Dec 20, 2022

sonarcloud bot commented Dec 21, 2022

sonarcloud bot commented Feb 6, 2023

derberg commented Feb 6, 2023

derberg commented Mar 27, 2023

sonarcloud bot commented Apr 4, 2023

derberg commented Apr 24, 2023

derberg commented Jul 19, 2023

derberg commented Sep 4, 2023

feat: improve help message for `new` command #320

feat: improve help message for `new` command #320

lakshz Jul 12, 2022 •

edited

Loading

lakshz commented Jul 29, 2022 •

edited

Loading

lakshz commented Jul 29, 2022 •

edited

Loading