1. Basics
This section covers the basics of Spring Shell. Before going on to define actual commands and options, we need to go through some of the fundamental concepts of Spring Shell.
Essentially, a few things needs to happen before you have a working Spring Shell application:
-
Create a Spring Boot application.
-
Define commands and options.
-
Package the application.
-
Run the application, either interactively or non-interactively.
You can get a full working Spring Shell application without defining any user-level commands
as some basic built-in commands (such as help and history) are provided.
|
Throughout this documentation, we make references to configuring something by using
annotations (mostly relates to use of The programmatic model is how things are actually registered, even if you use annotations.
The |
2. Commands
In this section, we go through an actual command registration and leave command options and execution for later in a documentation. You can find more detailed info in [appendix-tech-intro-registration].
2.1. Registration
There are two different ways to define a command: through an annotation model and through a programmatic model. In the annotation model, you define your methods in a class and annotate the class and the methods with specific annotations. In the programmatic model, you use a more low level approach, defining command registrations (either as beans or by dynamically registering with a command catalog).
2.1.1. Annotation Model
When you use the standard API, methods on beans are turned into executable commands, provided that:
-
The bean class bears the
@ShellComponentannotation. (This is used to restrict the set of beans that are considered.) -
The method bears the
@ShellMethodannotation.
|
The You can customize the name of the created bean by using the |
@ShellComponent
static class MyCommands {
@ShellMethod
public void mycommand() {
}
}
The only required attribute of the @ShellMethod annotation is its value attribute, which should have
a short, one-sentence, description of what the command does. This lets your users
get consistent help about your commands without having to leave the shell (see Help).
| The description of your command should be short — no more than one or two sentences. For better consistency, it should start with a capital letter and end with a period. |
By default, you need not specify the key for your command (that is, the word(s) that should be used
to invoke it in the shell). The name of the method is used as the command key, turning camelCase names into
dashed, gnu-style, names (for example, sayHello() becomes say-hello).
You can, however, explicitly set the command key, by using the key attribute of the annotation:
@ShellMethod(value = "Add numbers.", key = "sum")
public int add(int a, int b) {
return a + b;
}
The key attribute accepts multiple values.
If you set multiple keys for a single method, the command is registered with those different aliases.
|
| The command key can contain pretty much any character, including spaces. When coming up with names though, keep in mind that consistency is often appreciated by users. That is, you should avoid mixing dashed-names with spaced names and other inconsistencies. |
2.1.2. Programmatic Model
In the programmatic model, CommandRegistration can be defined as a @Bean
and it will be automatically registered.
@Bean
CommandRegistration commandRegistration() {
return CommandRegistration.builder()
.command("mycommand")
.build();
}
If all your commands have something in common, an instance of a CommandRegistration.BuilderSupplier is created which can be autowired. Default implementation of this supplier returns a new builder so you don’t need to worry about its internal state.
| Commands registered programmatically automatically add help options mentioned in Help Options. |
If bean of this supplier type is defined then auto-configuration will back off giving you an option to redefine default functionality.
@Bean
CommandRegistration commandRegistration(CommandRegistration.BuilderSupplier builder) {
return builder.get()
.command("mycommand")
.build();
}
CommandRegistrationCustomizer beans can be defined if you want to centrally
modify builder instance given you by supplier mentioned above.
@Bean
CommandRegistrationCustomizer commandRegistrationCustomizerExample() {
return builder -> {
// customize instance of CommandRegistration.Builder
};
}
2.2. Organizing Commands
When your shell starts to provide a lot of functionality, you may end up
with a lot of commands, which could be confusing for your users. By typing help,
they would see a daunting list of commands, organized in alphabetical order,
which may not always be the best way to show the available commands.
To alleviate this possible confusion, Spring Shell provides the ability to group commands together,
with reasonable defaults. Related commands would then end up in the same group (for example, User Management Commands)
and be displayed together in the help screen and other places.
By default, commands are grouped according to the class they are implemented in,
turning the camelCase class name into separate words (so URLRelatedCommands becomes URL Related Commands).
This is a sensible default, as related commands are often already in the class anyway,
because they need to use the same collaborating objects.
If, however, this behavior does not suit you, you can override the group for a command in the following ways, in order of priority:
-
Specify a
group()in the@ShellMethodannotation. -
Place a
@ShellCommandGroupon the class in which the command is defined. This applies the group for all commands defined in that class (unless overridden, as explained earlier). -
Place a
@ShellCommandGroupon the package (throughpackage-info.java) in which the command is defined. This applies to all the commands defined in the package (unless overridden at the method or class level, as explained earlier).
The following listing shows an example:
public class UserCommands {
@ShellMethod(value = "This command ends up in the 'User Commands' group")
public void foo() {}
@ShellMethod(value = "This command ends up in the 'Other Commands' group",
group = "Other Commands")
public void bar() {}
}
...
@ShellCommandGroup("Other Commands")
public class SomeCommands {
@ShellMethod(value = "This one is in 'Other Commands'")
public void wizz() {}
@ShellMethod(value = "And this one is 'Yet Another Group'",
group = "Yet Another Group")
public void last() {}
}
2.3. Dynamic Command Availability
Registered commands do not always make sense, due to the internal state of the application.
For example, there may be a download command, but it only works once the user has used connect on a remote
server. Now, if the user tries to use the download command, the shell should explain that
the command exists but that it is not available at the time.
Spring Shell lets you do that, even letting you provide a short explanation of the reason for
the command not being available.
There are three possible ways for a command to indicate availability.
They all use a no-arg method that returns an instance of Availability.
Consider the following example:
@ShellComponent
public class MyCommands {
private boolean connected;
@ShellMethod("Connect to the server.")
public void connect(String user, String password) {
[...]
connected = true;
}
@ShellMethod("Download the nuclear codes.")
public void download() {
[...]
}
public Availability downloadAvailability() {
return connected
? Availability.available()
: Availability.unavailable("you are not connected");
}
}
The connect method is used to connect to the server (details omitted), altering the state
of the command through the connected boolean when done.
The download command as marked as unavailable until the user has connected, thanks to the presence
of a method named exactly as the download command method with the Availability suffix in its name.
The method returns an instance of Availability, constructed with one of the two factory methods.
If the command is not available, an explanation has to be provided.
Now, if the user tries to invoke the command while not being connected, here is what happens:
shell:>download
Command 'download' exists but is not currently available because you are not connected.
Details of the error have been omitted. You can use the stacktrace command to print the full stacktrace.
Information about currently unavailable commands is also used in the integrated help. See Help.
|
The reason provided when the command is not available should read nicely if appended after “Because”. You should not start the sentence with a capital or add a final period |
If naming the availability method after the name of the command method does not suit you, you
can provide an explicit name by using the @ShellMethodAvailability annotation:
@ShellMethod("Download the nuclear codes.")
@ShellMethodAvailability("availabilityCheck") (1)
public void download() {
[...]
}
public Availability availabilityCheck() { (1)
return connected
? Availability.available()
: Availability.unavailable("you are not connected");
}
| 1 | the names have to match |
Finally, it is often the case that several commands in the same class share the same internal state and, thus,
should all be available or unavailable as a group. Instead of having to stick the @ShellMethodAvailability
on all command methods, Spring Shell lets you flip things around and put the @ShellMethodAvailabilty
annotation on the availability method, specifying the names of the commands that it controls:
@ShellMethod("Download the nuclear codes.")
public void download() {
[...]
}
@ShellMethod("Disconnect from the server.")
public void disconnect() {
[...]
}
@ShellMethodAvailability({"download", "disconnect"})
public Availability availabilityCheck() {
return connected
? Availability.available()
: Availability.unavailable("you are not connected");
}
|
The default value for the
|
| Spring Shell does not impose many constraints on how to write commands and how to organize classes. However, it is often good practice to put related commands in the same class, and the availability indicators can benefit from that. |
2.4. Exception Handling
Exceptions happen from a user code wether it is intentional or not. This section describes
how spring-shell handles exceptions and gives instructions and best practices how to
work with it.
Many command line applications when applicable return an exit code which running environment
can use to differentiate if command has been executed successfully or not. In a spring-shell
this mostly relates when a command is run on a non-interactive mode meaning one command
is always executed once with an instance of a spring-shell. Take a note that exit code
always relates to non-interactive shell.
2.4.1. Exception Resolving
Unhandled exceptions will bubble up into shell’s ResultHandlerService and then eventually
handled by some instance of ResultHandler. Chain of ExceptionResolver implementations
can be used to resolve exceptions and gives you flexibility to return message to get written
into console together with exit code which are wrapped within CommandHandlingResult.
CommandHandlingResult may contain a message and/or exit code.
static class CustomExceptionResolver implements CommandExceptionResolver {
@Override
public CommandHandlingResult resolve(Exception e) {
if (e instanceof CustomException) {
return CommandHandlingResult.of("Hi, handled exception\n", 42);
}
return null;
}
}
CommandExceptionResolver implementations can be defined globally as bean.
@Bean
CustomExceptionResolver customExceptionResolver() {
return new CustomExceptionResolver();
}
or defined per CommandRegistration if it’s applicable only for a particular command itself.
CommandRegistration.builder()
.withErrorHandling()
.resolver(new CustomExceptionResolver())
.and()
.build();
| Resolvers defined with a command are handled before global resolvers. |
Use you own exception types which can also be an instance of boot’s ExitCodeGenerator if
you want to define exit code there.
static class CustomException extends RuntimeException implements ExitCodeGenerator {
@Override
public int getExitCode() {
return 0;
}
}
2.4.2. Exit Code Mappings
Default behaviour of an exit codes is as:
-
Errors from a command option parsing will result code of
2 -
Any generic error will result result code of
1 -
Obviously in any other case result code is
0
Every CommandRegistration can define its own mappings between Exception and exit code.
Essentially we’re bound to functionality in Spring Boot regarding exit code and simply
integrate into that.
Assuming there is an exception show below which would be thrown from a command:
static class MyException extends RuntimeException {
private final int code;
MyException(String msg, int code) {
super(msg);
this.code = code;
}
public int getCode() {
return code;
}
}
It is possible to define a mapping function between Throwable and exit code. You can also
just configure a class to exit code which is just a syntactic sugar within configurations.
CommandRegistration.builder()
.withExitCode()
.map(MyException.class, 3)
.map(t -> {
if (t instanceof MyException) {
return ((MyException) t).getCode();
}
return 0;
})
.and()
.build();
| Exit codes cannot be customized with annotation based configuration |
2.4.3. @ExceptionResolver
@ShellComponent classes can have @ExceptionResolver methods to handle exceptions from component
methods. These are meant for annotated methods.
The exception may match against a top-level exception being propagated (e.g. a direct IOException being thrown) or against a nested cause within a wrapper exception (e.g. an IOException wrapped inside an IllegalStateException). This can match at arbitrary cause levels.
For matching exception types, preferably declare the target exception as a method argument, as the preceding example(s) shows. When multiple exception methods match, a root exception match is generally preferred to a cause exception match. More specifically, the ExceptionDepthComparator is used to sort exceptions based on their depth from the thrown exception type.
Alternatively, the annotation declaration may narrow the exception types to match, as the following example shows:
@ExceptionResolver({ RuntimeException.class })
CommandHandlingResult errorHandler(Exception e) {
// Exception would be type of RuntimeException,
// optionally do something with it
return CommandHandlingResult.of("Hi, handled exception\n", 42);
}
@ExceptionResolver
CommandHandlingResult errorHandler(RuntimeException e) {
return CommandHandlingResult.of("Hi, handled custom exception\n", 42);
}
@ExceptionResolver can also return String which is used as an output to console. You can
use @ExitCode annotation to define return code.
@ExceptionResolver
@ExitCode(code = 5)
String errorHandler(Exception e) {
return "Hi, handled exception";
}
@ExceptionResolver with void return type is automatically handled as handled exception.
You can then also define @ExitCode and use Terminal if you need to write something
into console.
@ExceptionResolver
@ExitCode(code = 5)
void errorHandler(Exception e, Terminal terminal) {
PrintWriter writer = terminal.writer();
String msg = "Hi, handled exception " + e.toString();
writer.println(msg);
writer.flush();
}
Method Arguments
@ExceptionResolver methods support the following arguments:
| Method argument | Description |
|---|---|
Exception type |
For access to the raised exception. This is any type of |
Terminal |
For access to underlying |
Return Values
@ExceptionResolver methods support the following return values:
| Return value | Description |
|---|---|
String |
Plain text to return to a shell. Exit code 1 is used in this case. |
CommandHandlingResult |
Plain |
void |
A method with a void return type is considered to have fully handled the exception. Usually
you would define |
2.5. Hidden Command
It is possible to hide a command which is convenient in cases where it is not yet ready for prime time, is meant for debugging purposes or you have any other reason you dont want to advertise its presense.
Hidden command can be executed if you know it and its options. It is effectively removed from:
-
Help listing
-
Help page for command return "unknown command"
-
Command completion in interactive mode
-
Bash completion
Below is an example how to define command as hidden. It shows available builder methods to define hidden state.
CommandRegistration commandRegistration() {
return CommandRegistration.builder()
.command("mycommand")
// define as hidden
.hidden()
// can be defined via a flag (false)
.hidden(false)
// can be defined via a flag (true)
.hidden(true)
.build();
}
| Defining hidden commands is not supported with annotation based configuration |
2.6. Help Options
Spring Shell has a build-in help command but not all favour getting command help
from it as you always need to call it with arguments for target command. It’s
common in many cli frameworks for every command having options --help and -h
to print out command help.
Default functionality is that every command will get modified to have options
--help and -h, which if present in a given command will automatically
short circuit command execution into a existing help command regardless
what other command-line options is typed.
Below example shows its default settings.
@Bean
CommandRegistration commandRegistration() {
return CommandRegistration.builder()
.command("mycommand")
.withHelpOptions()
.enabled(true)
.longNames("help")
.shortNames('h')
.command("help")
.and()
.build();
}
It is possible to change default behaviour via configuration options.
spring:
shell:
help:
enabled: true
long-names: help
short-names: h
command: help
| Commands defined programmationally or via annotations will automatically add help options. With annotation model you can only turn things off globally, programmatic model gives option to modify settings per command. |
2.7. Interaction Mode
Command registration can define InteractionMode which is used to hide commands
depending which mode shell is executing. More about that in Interaction Mode.
You can define it with CommandRegisration.
CommandRegistration commandRegistration() {
return CommandRegistration.builder()
.command("mycommand")
// can be defined for all modes
.interactionMode(InteractionMode.ALL)
// can be defined only for interactive
.interactionMode(InteractionMode.INTERACTIVE)
// can be defined only for non-interactive
.interactionMode(InteractionMode.NONINTERACTIVE)
.build();
}
Or with @ShellMethod.
@ShellMethod(key = "mycommand", interactionMode = InteractionMode.INTERACTIVE)
public void mycommand() {
}
2.8. Built-In Commands
2.8.1. Help
Running a shell application often implies that the user is in a graphically limited
environment. Also, while we are nearly always connected in the era of mobile phones,
accessing a web browser or any other rich UI application (such as a PDF viewer) may not always
be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the help
command comes in.
Typing help + ENTER lists all the commands known to the shell (including unavailable commands)
and a short description of what they do, similar to the following:
my-shell:>help
AVAILABLE COMMANDS
Built-In Commands
exit: Exit the shell.
help: Display help about available commands
stacktrace: Display the full stacktrace of the last error.
clear: Clear the shell screen.
quit: Exit the shell.
history: Display or save the history of previously run commands
completion bash: Generate bash completion script
version: Show version info
script: Read and execute commands from a file.
Typing help <command> shows more detailed information about a command, including the available parameters, their
type, whether they are mandatory or not, and other details.
The following listing shows the help command applied to itself:
my-shell:>help help
NAME
help - Display help about available commands
SYNOPSIS
help --command String
OPTIONS
--command or -C String
The command to obtain help for.
[Optional]
Help is templated and can be customized if needed. Settings are under spring.shell.command.help where you can use
enabled to disable command, grouping-mode taking group or flat if you want to hide groups by flattening
a structure, command-template to define your template for output of a command help, commands-template to define
output of a command list.
If spring.shell.command.help.grouping-mode=flat is set, then help would show:
my-shell:>help help
AVAILABLE COMMANDS
exit: Exit the shell.
help: Display help about available commands
stacktrace: Display the full stacktrace of the last error.
clear: Clear the shell screen.
quit: Exit the shell.
history: Display or save the history of previously run commands
completion bash: Generate bash completion script
version: Show version info
script: Read and execute commands from a file.
Output from help and help <commmand> are both templated with a default implementation
which can be changed.
Option spring.shell.command.help.commands-template defaults to
classpath:template/help-commands-default.stg and is passed GroupsInfoModel
as a model.
Option spring.shell.command.help.command-template defaults to
classpath:template/help-command-default.stg and is passed CommandInfoModel
as a model.
| Key | Description |
|---|---|
|
|
|
The commands variables (see GroupCommandInfoModel Variables). |
|
The commands variables (see CommandInfoModel Variables). |
|
|
| Key | Description |
|---|---|
|
The name of a group, if set. Otherwise, empty. |
|
The commands, if set. Otherwise, empty. Type is a multi value, see CommandInfoModel Variables. |
| Key | Description |
|---|---|
|
The name of a command, if set. Otherwise, null. Type is string and contains full command. |
|
The names of a command, if set. Otherwise, null. Type is multi value essentially |
|
The possible aliases, if set. Type is multi value with strings. |
|
The description of a command, if set. Otherwise, null. |
|
The parameters variables, if set. Otherwise empty. Type is a multi value, see CommandParameterInfoModel Variables. |
|
The availability variables (see CommandAvailabilityInfoModel Variables). |
| Key | Description |
|---|---|
|
The type of a parameter if set. Otherwise, null. |
|
The arguments, if set. Otherwise, null. Type is multi value with strings. |
|
|
|
The description of a parameter, if set. Otherwise, null. |
|
The default value of a parameter, if set. Otherwise, null. |
|
|
| Key | Description |
|---|---|
|
|
|
The reason if not available if set. Otherwise, null. |
2.8.2. Clear
The clear command does what you would expect and clears the screen, resetting the prompt
in the top left corner.
2.8.3. Exit
The quit command (also aliased as exit) requests the shell to quit, gracefully
closing the Spring application context. If not overridden, a JLine History bean writes a history of all
commands to disk, so that they are available again on the next launch.
2.8.4. Stacktrace
When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed so as not to overflow the user with too much information. There are cases, though, when understanding what exactly happened is important (especially if the exception has a nested cause).
To this end, Spring Shell remembers the last exception that occurred, and the user can later use the stacktrace
command to print all the details on the console.
2.8.5. Script
The script command accepts a local file as an argument and replays commands found there, one at a time.
Reading from the file behaves exactly like inside the interactive shell, so lines starting with // are considered
to be comments and are ignored, while lines ending with \ trigger line continuation.
2.8.6. History
The history command shows the history of commands that has been executed.
There are a few configuration options that you can use to configure behavior
of a history. History is kept in a log file, which is enabled by default and can
be turned off by setting spring.shell.history.enabled. The name of a log file
is resolved from spring.application.name and defaults to spring-shell.log,
which you can change by setting spring.shell.history.name.
By default, a log file is generated to a current working directory, which you can dictate
by setting spring.shell.config.location. This property can contain
a placeholder ({userconfig}), which resolves to a common shared config directory.
| Run the Spring Shell application to see how the sample application works as it uses these options. |
2.8.7. Completion
The completion command set lets you create script files that can be used
with am OS shell implementations to provide completion. This is very useful when
working with non-interactive mode.
Currently, the only implementation is for bash, which works with bash sub-command.
2.8.8. Version
The version command shows existing build and git info by integrating into
Boot’s BuildProperties and GitProperties if those exist in the shell application.
By default, only version information is shown, and you can enable other information through configuration
options.
The relevant settings are under spring.shell.command.version, where you can use enabled to
disable a command and, optionally, define your own template with template. You can use the
show-build-artifact, show-build-group, show-build-name, show-build-time,
show-build-version, show-git-branch, show-git-commit-id,
show-git-short-commit-id and show-git-commit-time commands to control
fields in a default template.
The template defaults to classpath:template/version-default.st, and you can define
your own, as the following example shows:
<buildVersion>
This setting would output something like the following:
X.X.X
You can add the following attributes to the default template rendering: buildVersion, buildGroup,
buildGroup, buildName, buildTime, gitShortCommitId, gitCommitId,
gitBranch, and gitCommitTime.
2.9. Writing
When something needs to get written into your console you can always
use JDK’s System.out which then goes directly into JDK’s own streams.
Other recommended way is to use JLine’s Terminal and get writer
instance from there.
If using target endpoints, i.e. consumer which is not expected
to return anything given CommandContext contains reference to
Terminal and writer can be accessed from there.
CommandRegistration.builder()
.command("example")
.withTarget()
.consumer(ctx -> {
ctx.getTerminal().writer().println("hi");
ctx.getTerminal().writer().flush();
})
.and()
.build();
It’s possible to autowire Terminal to get access to its writer.
@Autowired
Terminal terminal;
@ShellMethod
public void example() {
terminal.writer().println("hi");
terminal.writer().flush();
}
3. Options
Command line arguments can be separated into options and positional parameters. Following sections describes features how options are defined and used.
3.1. Definition
Options can be defined within a target method as annotations in a method arguments
or with programmatically with CommandRegistration.
Having a target method with argument is automatically registered with a matching argument name.
public String example(String arg1) {
return "Hello " + arg1;
}
@ShellOption annotation can be used to define an option name if you
don’t want it to be same as argument name.
public String example(@ShellOption(value = { "--argx" }) String arg1) {
return "Hello " + arg1;
}
If option name is defined without prefix, either - or --, it is discovered
from ShellMethod#prefix.
public String example(@ShellOption(value = { "argx" }) String arg1) {
return "Hello " + arg1;
}
Programmatic way with CommandRegistration is to use method adding a long name.
CommandRegistration.builder()
.withOption()
.longNames("arg1")
.and()
.build();
3.2. Short Format
Short style POSIX option in most is just a synonym to long format but
adds additional feature to combine those options together. Having short
options a, b, c can be used as -abc.
Programmatically short option is defined by using short name function.
CommandRegistration.builder()
.withOption()
.shortNames('a')
.and()
.withOption()
.shortNames('b')
.and()
.withOption()
.shortNames('c')
.and()
.build();
Short option with combined format is powerful if type is defined as a flag
which means type is a boolean. That way you can define a presense of a flags
as -abc, -abc true or -abc false.
CommandRegistration.builder()
.withOption()
.shortNames('a')
.type(boolean.class)
.and()
.withOption()
.shortNames('b')
.type(boolean.class)
.and()
.withOption()
.shortNames('c')
.type(boolean.class)
.and()
.build();
With annotation model you can define short argument directly.
public String example(
@ShellOption(value = { "-a" }) String arg1,
@ShellOption(value = { "-b" }) String arg2,
@ShellOption(value = { "-c" }) String arg3
) {
return "Hello " + arg1;
}
3.3. Arity
Sometimes, you want to have more fine control of how many parameters with an option are processed when parsing operations happen. Arity is defined as min and max values, where min must be a positive integer and max has to be more or equal to min.
CommandRegistration.builder()
.withOption()
.longNames("arg1")
.arity(0, 1)
.and()
.build();
Arity can also be defined as an OptionArity enum, which are shortcuts
within the following table:
CommandRegistration.builder()
.withOption()
.longNames("arg1")
.arity(OptionArity.EXACTLY_ONE)
.and()
.build();
| Value | min/max |
|---|---|
ZERO |
0 / 0 |
ZERO_OR_ONE |
0 / 1 |
EXACTLY_ONE |
1 / 1 |
ZERO_OR_MORE |
0 / Integer MAX |
ONE_OR_MORE |
1 / Integer MAX |
The annotation model supports defining only the max value of an arity.
public String example(@ShellOption(arity = 1) String arg1) {
return "Hello " + arg1;
}
3.4. Positional
Positional information is mostly related to a command target method:
CommandRegistration.builder()
.withOption()
.longNames("arg1")
.position(0)
.and()
.build();
3.5. Optional Value
An option is either required or not and, generally speaking, how it behaves depends on a command target:
CommandRegistration.builder()
.withOption()
.longNames("arg1")
.required()
.and()
.build();
In the annotation model, there is no direct way to define if argument is
optional. Instead, it is instructed to be NULL:
public String example(
@ShellOption(defaultValue = ShellOption.NULL) String arg1
) {
return "Hello " + arg1;
}
3.6. Default Value
Having a default value for an option is somewhat related to Optional Value, as there are cases where you may want to know if the user defined an option and change behavior based on a default value:
CommandRegistration.builder()
.withOption()
.longNames("arg1")
.defaultValue("defaultValue")
.and()
.build();
The annotation model also supports defining default values:
public String example(
@ShellOption(defaultValue = "defaultValue") String arg1
) {
return "Hello " + arg1;
}
3.7. Validation
Spring Shell integrates with the Bean Validation API to support automatic and self-documenting constraints on command parameters.
Annotations found on command parameters and annotations at the method level are honored and trigger validation prior to the command executing. Consider the following command:
@ShellMethod("Change password.")
public String changePassword(@Size(min = 8, max = 40) String password) {
return "Password successfully set to " + password;
}
From the preceding example, you get the following behavior for free:
shell:>change-password hello The following constraints were not met: --password string : size must be between 8 and 40 (You passed 'hello')
3.8. Label
Option Label has no functional behaviour within a shell itself other than
what a default help command outputs. Within a command documentation
a type of an option is documented but this is not always super useful. Thus
you may want to give better descriptive word for an option.
CommandRegistration.builder()
.withOption()
.longNames("arg1")
.and()
.withOption()
.longNames("arg2")
.label("MYLABEL")
.and()
.build();
Defining label is then shown in help.
my-shell:>help mycommand
NAME
mycommand -
SYNOPSIS
mycommand --arg1 String --arg2 MYLABEL
OPTIONS
--arg1 String
[Optional]
--arg2 MYLABEL
[Optional]
3.9. Types
This section talks about how particular data type is used as an option value.
3.9.1. String
String is a most simplest type as there’s no conversion involved as what’s
coming in from a user is always a string.
String example(@ShellOption(value = "arg1") String arg1) {
return "Hello " + arg1;
}
While it’s not strictly required to define type as a String it’s always
adviced to do so.
CommandRegistration.builder()
.command("example")
.withOption()
.longNames("arg1")
.type(String.class)
.required()
.and()
.withTarget()
.function(ctx -> {
String arg1 = ctx.getOptionValue("arg1");
return "Hello " + arg1;
})
.and()
.build();
3.9.2. Boolean
Using boolean types is a bit more involved as there are boolean and
Boolean where latter can be null. Boolean types are usually used as
flags meaning argument value may not be needed.
String example(
@ShellOption() boolean arg1,
@ShellOption(defaultValue = "true") boolean arg2,
@ShellOption(defaultValue = "false") boolean arg3,
@ShellOption() Boolean arg4,
@ShellOption(defaultValue = "true") Boolean arg5,
@ShellOption(defaultValue = "false") Boolean arg6
) {
return String.format("arg1=%s arg2=%s arg3=%s arg4=%s arg5=%s arg6=%s",
arg1, arg2, arg3, arg4, arg5, arg6);
}
shell:>example
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
shell:>example --arg4
arg1=false arg2=true arg3=false arg4=true arg5=true arg6=false
shell:>example --arg4 false
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
CommandRegistration.builder()
.command("example")
.withOption()
.longNames("arg1").type(boolean.class).and()
.withOption()
.longNames("arg2").type(boolean.class).defaultValue("true").and()
.withOption()
.longNames("arg3").type(boolean.class).defaultValue("false").and()
.withOption()
.longNames("arg4").type(Boolean.class).and()
.withOption()
.longNames("arg5").type(Boolean.class).defaultValue("true").and()
.withOption()
.longNames("arg6").type(Boolean.class).defaultValue("false").and()
.withTarget()
.function(ctx -> {
boolean arg1 = ctx.hasMappedOption("arg1")
? ctx.getOptionValue("arg1")
: false;
boolean arg2 = ctx.getOptionValue("arg2");
boolean arg3 = ctx.getOptionValue("arg3");
Boolean arg4 = ctx.getOptionValue("arg4");
Boolean arg5 = ctx.getOptionValue("arg5");
Boolean arg6 = ctx.getOptionValue("arg6");
return String.format("Hello arg1=%s arg2=%s arg3=%s arg4=%s arg5=%s arg6=%s",
arg1, arg2, arg3, arg4, arg5, arg6);
})
.and()
.build();
shell:>example
arg1=false arg2=true arg3=false arg4=null arg5=true arg6=false
shell:>example --arg4
arg1=false arg2=true arg3=false arg4=true arg5=true arg6=false
shell:>example --arg4 false
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
3.9.3. Number
Numbers are converted as is.
String example(@ShellOption(value = "arg1") int arg1) {
return "Hello " + arg1;
}
CommandRegistration.builder()
.command("example")
.withOption()
.longNames("arg1")
.type(int.class)
.required()
.and()
.withTarget()
.function(ctx -> {
boolean arg1 = ctx.getOptionValue("arg1");
return "Hello " + arg1;
})
.and()
.build();
3.9.4. Enum
Conversion to enums is possible if given value is exactly matching enum itself. Currently you can convert assuming case insensitivity.
enum OptionTypeEnum {
ONE,TWO,THREE
}
String example(@ShellOption(value = "arg1") OptionTypeEnum arg1) {
return "Hello " + arg1;
}
CommandRegistration.builder()
.command("example")
.withOption()
.longNames("arg1")
.type(OptionTypeEnum.class)
.required()
.and()
.withTarget()
.function(ctx -> {
OptionTypeEnum arg1 = ctx.getOptionValue("arg1");
return "Hello " + arg1;
})
.and()
.build();
4. Completion
Spring Shell can provide completion proposals for both interactive shell and a command-line. There are differences however as when shell is in interactive mode we have an active instance of a shell meaning it’s easier to provide more programmatic ways to provide completion hints. When shell is purely run as a command-line tool a completion can only be accomplished with integration into OS level shell’s like bash.
4.1. Interactive
Hints for completions are calculated with function or interface style
methods which takes CompletionContext and returns a list of
CompletionProposal instances. CompletionContext gives you various
information about a current context like command registration and option.
Generic resolvers can be registered as a beans if those are useful
for all commands and scenarious. For example existing completion
implementation RegistrationOptionsCompletionResolver handles completions
for a option names.
|
static class MyValuesCompletionResolver implements CompletionResolver {
@Override
public List<CompletionProposal> apply(CompletionContext t) {
return Arrays.asList("val1", "val2").stream()
.map(CompletionProposal::new)
.collect(Collectors.toList());
}
}
Option values with builder based command registration can be defined per option.
void dump1() {
CommandRegistration.builder()
.withOption()
.longNames("arg1")
.completion(ctx -> {
return Arrays.asList("val1", "val2").stream()
.map(CompletionProposal::new)
.collect(Collectors.toList());
})
.and()
.build();
}
Option values with annotation based command registration are handled
via ValueProvider interface which can be defined with @ShellOption
annotation.
static class MyValuesProvider implements ValueProvider {
@Override
public List<CompletionProposal> complete(CompletionContext completionContext) {
return Arrays.asList("val1", "val2").stream()
.map(CompletionProposal::new)
.collect(Collectors.toList());
}
}
Actual ValueProvider with annotation based command needs to be
registered as a Bean.
@ShellMethod(value = "complete", key = "complete")
public String complete(
@ShellOption(valueProvider = MyValuesProvider.class) String arg1)
{
return "You said " + arg1;
}
4.2. Command-Line
Command-line completion currently only support bash and is documented
in a built-in completion command Completion.
5. Building
This section covers how to build a Spring Shell application.
5.1. Native Support
Support for compiling Spring Shell application into a GraalVM binary mostly comes from Spring Framework and Spring Boot where feature is called AOT. Ahead of Time means that application context is prepared during the compilation time to being ready for GraalVM generation.
Building atop of AOT features from a framework Spring Shell has its own GraalVM configuration providing hints what should exist in a binary. Usually trouble comes from a 3rd party libraries which doesn’t yet contain GraalVM related configurations or those configurations are incomplete.
It is requred to use GraalVM Reachability Metadata Repository which
provides some missing hints for 3rd party libraries. Also you need to have
GraalVM installed and JAVA_HOME pointing to that.
|
For gradle add graalvm’s native plugin and configure metadata repository.
plugins {
id 'org.graalvm.buildtools.native' version '0.9.16'
}
graalvmNative {
metadataRepository {
enabled = true
}
}
When gradle build is run with ./gradlew nativeCompile you should get binary
under build/native/nativeCompile directory.
For maven use spring-boot-starter-parent as parent and you’ll get native
profile which can be used to do a compilation. You need to configure metadata repository
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<configuration>
<metadataRepository>
<enabled>true</enabled>
</metadataRepository>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
If you rely on spring-boot-starter-parent it manages native-maven-plugin
version which is kept up to date.
|
When maven build is run with ./mvnw package -Pnative you should get binary
under target directory.
If everything went well this binary can be run as is instead of executing boot application jar via jvm.
6. Components
Components are a set of features which are either build-in or something you can re-use or extend for your own needs. Components in question are either built-in commands or UI side components providing higher level features within commands itself.
6.1. Flow
When you use Flow Components to build something that involves
use of a multiple components, your implementation may become a bit cluttered.
To ease these use cases, we added a
ComponentFlow that can hook multiple component executions together
as a “flow”.
The following listings show examples of flows and their output in a shell:
static class FlowSampleComplex {
@Autowired
private ComponentFlow.Builder componentFlowBuilder;
public void runFlow() {
Map<String, String> single1SelectItems = new HashMap<>();
single1SelectItems.put("key1", "value1");
single1SelectItems.put("key2", "value2");
List<SelectItem> multi1SelectItems = Arrays.asList(SelectItem.of("key1", "value1"),
SelectItem.of("key2", "value2"), SelectItem.of("key3", "value3"));
ComponentFlow flow = componentFlowBuilder.clone().reset()
.withStringInput("field1")
.name("Field1")
.defaultValue("defaultField1Value")
.and()
.withStringInput("field2")
.name("Field2")
.and()
.withConfirmationInput("confirmation1")
.name("Confirmation1")
.and()
.withPathInput("path1")
.name("Path1")
.and()
.withSingleItemSelector("single1")
.name("Single1")
.selectItems(single1SelectItems)
.and()
.withMultiItemSelector("multi1")
.name("Multi1")
.selectItems(multi1SelectItems)
.and()
.build();
flow.run();
}
}
Normal execution order of a components is same as defined with a builder. It’s
possible to conditionally choose where to jump in a flow by using a next
function and returning target component id. If this returned id is aither null
or doesn’t exist flow is essentially stopped right there.
static class FlowSampleConditional {
@Autowired
private ComponentFlow.Builder componentFlowBuilder;
public void runFlow() {
Map<String, String> single1SelectItems = new HashMap<>();
single1SelectItems.put("Field1", "field1");
single1SelectItems.put("Field2", "field2");
ComponentFlow flow = componentFlowBuilder.clone().reset()
.withSingleItemSelector("single1")
.name("Single1")
.selectItems(single1SelectItems)
.next(ctx -> ctx.getResultItem().get().getItem())
.and()
.withStringInput("field1")
.name("Field1")
.defaultValue("defaultField1Value")
.next(ctx -> null)
.and()
.withStringInput("field2")
.name("Field2")
.defaultValue("defaultField2Value")
.next(ctx -> null)
.and()
.build();
flow.run();
}
}
The result from running a flow returns ComponentFlowResult, which you can
use to do further actions.
|
6.2. Flow Components
Starting from version 2.1.x, a new component model provides an easier way to create higher-level user interaction for the usual use cases, such as asking for input in various forms. These usually are just plain text input or choosing something from a list.
Templates for built-in components are in the
org/springframework/shell/component classpath.
Built-in components generally follow this logic:
-
Enter a run loop for user input.
-
Generate component-related context.
-
Render the runtime status of a component state.
-
Exit.
-
Render the final status of a component state.
| Flow gives better interface for defining the flow of components that are better suited for defining interactive command flows. |
6.2.1. Component Render
You can implement component rendering in either of two ways: fully
programmatically or by using a ANTLR Stringtemplate.
Strictly speaking, there is a simple Function renderer interface
that takes Context as an input and outputs a list of AttributedString.
This lets you choose between templating and code.
Templating is a good choice if you do not need to do anything complex or you just want to slightly modify existing component layouts. Rendering through code then gives you flexibility to do whatever you need.
The programmatic way to render is to create a Function:
class StringInputCustomRenderer implements Function<StringInputContext, List<AttributedString>> {
@Override
public List<AttributedString> apply(StringInputContext context) {
AttributedStringBuilder builder = new AttributedStringBuilder();
builder.append(context.getName());
builder.append(" ");
if (context.getResultValue() != null) {
builder.append(context.getResultValue());
}
else {
String input = context.getInput();
if (StringUtils.hasText(input)) {
builder.append(input);
}
else {
builder.append("[Default " + context.getDefaultValue() + "]");
}
}
return Arrays.asList(builder.toAttributedString());
}
}
Then you can hook it to a component:
@ShellMethod(key = "component stringcustom", value = "String input", group = "Components")
public String stringInputCustom(boolean mask) {
StringInput component = new StringInput(getTerminal(), "Enter value", "myvalue",
new StringInputCustomRenderer());
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
if (mask) {
component.setMaskCharater('*');
}
StringInputContext context = component.run(StringInputContext.empty());
return "Got value " + context.getResultValue();
}
Components have their own context but usually share some functionality from a parent component types. The following tables show those context variables:
| Key | Description |
|---|---|
|
The value after a component renders its result. |
|
The name of a component — that is, its title. |
|
The possible message set for a component. |
|
The level of a message — one of |
|
Return |
|
Return |
|
Return |
|
The raw user input. |
| Key | Description |
|---|---|
|
The name of a component — that is, its title. |
|
The raw user input — mostly used for filtering. |
|
The full list of item states. |
|
The visible list of item states. |
|
Return |
|
The current cursor row in a selector. |
| Key | Description |
|---|---|
|
The width of terminal, type is Integer and defaults to NULL if not set. |
6.2.2. String Input
The string input component asks a user for simple text input, optionally masking values if the content contains something sensitive. The following listing shows an example:
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component string", value = "String input", group = "Components")
public String stringInput(boolean mask) {
StringInput component = new StringInput(getTerminal(), "Enter value", "myvalue");
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
if (mask) {
component.setMaskCharater('*');
}
StringInputContext context = component.run(StringInputContext.empty());
return "Got value " + context.getResultValue();
}
}
The following image shows typical output from a string input component:
The context object is StringInputContext. The following table lists its context variables:
| Key | Description |
|---|---|
|
The default value, if set. Otherwise, null. |
|
The masked input value |
|
The masked result value |
|
The mask character, if set. Otherwise, null. |
|
|
|
The parent context variables (see TextComponentContext Template Variables). |
6.2.3. Path Input
The path input component asks a user for a Path and gives additional information about a path itself.
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component path input", value = "Path input", group = "Components")
public String pathInput() {
PathInput component = new PathInput(getTerminal(), "Enter value");
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
PathInputContext context = component.run(PathInputContext.empty());
return "Got value " + context.getResultValue();
}
}
The following image shows typical output from a path input component:
The context object is PathInputContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The parent context variables (see TextComponentContext Template Variables). |
6.2.4. Path Search
The path search component asks base directory for scan and optional search expression.
Results are shown in a single select list where user can pick a path.
PathSearchConfig can be used to customise component behaviour.
PathSearchConfig config = new PathSearch.PathSearchConfig();
config.setMaxPathsShow(5);
config.setMaxPathsSearch(100);
config.setSearchForward(true);
config.setSearchCaseSensitive(false);
config.setSearchNormalize(false);
PathSearch component = new PathSearch(getTerminal(), "Enter value", config);
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
PathSearchContext context = component.run(PathSearchContext.empty());
return "Got value " + context.getResultValue();
| Logic for search is passed as is into algorithms documented in [appendix-tech-intro-searchalgorithm]. |
The following image shows typical output from a path search component:
The context object is PathSearchContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The items available for rendering search results. |
|
The parent context variables (see TextComponentContext Template Variables). |
6.2.5. Confirmation
The confirmation component asks a user for a simple confirmation. It is essentially a yes-or-no question.
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component confirmation", value = "Confirmation input", group = "Components")
public String confirmationInput(boolean no) {
ConfirmationInput component = new ConfirmationInput(getTerminal(), "Enter value", !no);
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
ConfirmationInputContext context = component.run(ConfirmationInputContext.empty());
return "Got value " + context.getResultValue();
}
}
The following image shows the typical output from a confirmation component:
The context object is ConfirmationInputContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The default value — either |
|
The parent context variables (see TextComponentContext Template Variables). |
6.2.6. Single Select
A single select component asks a user to choose one item from a list. It is similar to a simple dropbox implementation. The following listing shows an example:
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component single", value = "Single selector", group = "Components")
public String singleSelector() {
SelectorItem<String> i1 = SelectorItem.of("key1", "value1");
SelectorItem<String> i2 = SelectorItem.of("key2", "value2");
List<SelectorItem<String>> items = Arrays.asList(i1, i2);
SingleItemSelector<String, SelectorItem<String>> component = new SingleItemSelector<>(getTerminal(),
items, "testSimple", null);
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
SingleItemSelectorContext<String, SelectorItem<String>> context = component
.run(SingleItemSelectorContext.empty());
String result = context.getResultItem().flatMap(si -> Optional.ofNullable(si.getItem())).get();
return "Got value " + result;
}
}
The following image shows typical output for a single select component:
The context object is SingleItemSelectorContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The returned value when the component exists. |
|
The visible items, where rows contains maps of name and selected items. |
|
The parent context variables (see SelectorComponentContext Template Variables). |
You can pre-select an item by defining it to get exposed. This is
useful if you know the default and lets the user merely press Enter to make a choice.
The following listing sets a default:
SelectorItem<String> i1 = SelectorItem.of("key1", "value1");
SelectorItem<String> i2 = SelectorItem.of("key2", "value2");
List<SelectorItem<String>> items = Arrays.asList(i1, i2);
SingleItemSelector<String, SelectorItem<String>> component = new SingleItemSelector<>(getTerminal(),
items, "testSimple", null);
component.setDefaultExpose(i2);
6.2.7. Multi Select
The multi select component asks a user to select multiple items from a list. The following listing shows an example:
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component multi", value = "Multi selector", group = "Components")
public String multiSelector() {
List<SelectorItem<String>> items = new ArrayList<>();
items.add(SelectorItem.of("key1", "value1"));
items.add(SelectorItem.of("key2", "value2", false, true));
items.add(SelectorItem.of("key3", "value3"));
MultiItemSelector<String, SelectorItem<String>> component = new MultiItemSelector<>(getTerminal(),
items, "testSimple", null);
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
MultiItemSelectorContext<String, SelectorItem<String>> context = component
.run(MultiItemSelectorContext.empty());
String result = context.getResultItems().stream()
.map(si -> si.getItem())
.collect(Collectors.joining(","));
return "Got value " + result;
}
}
The following image shows a typical multi-select component:
The context object is MultiItemSelectorContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The values returned when the component exists. |
|
The visible items, where rows contain maps of name, selected, on-row, and enabled items. |
|
The parent context variables (see SelectorComponentContext Template Variables). |
7. Customization
This section describes how you can customize the shell.
7.1. Theming
Current terminal implementations are rich in features and can usually show something else that just plain text. For example a text can be styled to be bold or have different colors. It’s also common for terminals to be able to show various characters from an unicode table like emoji’s which are usually used to make shell output more pretty.
Spring Shell supports these via it’s theming framework which contains two parts, firstly styling can be used to change text type and secondly figures how some characters are shown. These two are then combined together as a theme.
More about theming internals, see [appendix-tech-intro-theming].
Default theme is named default but can be change using property
spring.shell.theme.name. Other built-in theme named dump uses
no styling for colors and tries to not use any special figures.
|
Modify existing style by overriding settings.
static class MyStyleSettings extends StyleSettings {
@Override
public String highlight() {
return super.highlight();
}
}
Modify existing figures by overriding settings.
static class MyFigureSettings extends FigureSettings {
@Override
public String error() {
return super.error();
}
}
To create a new theme, create a ThemeSettings and provide your own style
and figure implementations.
static class MyThemeSettings extends ThemeSettings {
@Override
public StyleSettings styles() {
return new MyStyleSettings();
}
@Override
public FigureSettings figures() {
return new MyFigureSettings();
}
}
Register a new bean Theme where you can return your custom ThemeSettings
and a theme name.
@Configuration
static class CustomThemeConfig {
@Bean
Theme myTheme() {
return new Theme() {
@Override
public String getName() {
return "mytheme";
}
@Override
public ThemeSettings getSettings() {
return new MyThemeSettings();
}
};
}
}
You can use ThemeResolver to resolve styles if you want to create
JLine-styled strings programmatically and figures if you want to
theme characters for being more pretty.
@Autowired
private ThemeResolver resolver;
void resolve() {
String resolvedStyle = resolver.resolveStyleTag(StyleSettings.TAG_TITLE);
// bold,fg:bright-white
AttributedStyle style = resolver.resolveStyle(resolvedStyle);
// jline attributed style from expression above
String resolvedFigure = resolver.resolveFigureTag(FigureSettings.TAG_ERROR);
// character i.e. U+2716 Heavy Multiplication X Emoji, cross
}
7.2. Logging
On default a Spring Boot application will log messages into a console which at minimum is annoying and may also mix output from a shell commands. Fortunately there is a simple way to instruct logging changes via boot properties.
Completely silence console logging by defining its pattern as an empty value.
logging:
pattern:
console:
If you need log from a shell then write those into a file.
logging:
file:
name: shell.log
If you need different log levels.
logging:
level:
org:
springframework:
shell: debug
Passing contiguration properties as command line options is not supported but you can use any other ways supported by boot, for example.
$ java -Dlogging.level.root=debug -jar demo.jar
$ LOGGING_LEVEL_ROOT=debug java -jar demo.jar
| In a GraalVM image settings are locked during compilation which means you can’t change log levels at runtime. |
8. Execution
This section describes how to set up a Spring Shell to work in interactive mode.
8.1. Interaction Mode
Version 2.1.x introduced built-in support to distinguish between interactive and non-interactive modes. This makes it easier to use the shell as a simple command-line tool without requiring customization.
Currently, interactive mode is entered if any command line options are passed when starting or running a shell from a command line. This works especially well when a shell application is compiled with Native Support.
Some commands may not have any useful meanings when they run in interactive mode
or (conversely) in non-interactive mode. For example, a built-in exit command would
have no meaning in non-interactive mode, because it is used to exit interactive mode.
The @ShellMethod annotation has a field called interactionMode that you can use to inform
shell about when a particular command is available.
8.2. Shell Runners
ShellApplicationRunner is a main interface where Boot’s ApplicationArguments are passed
and its default implementation makes a choice which ShellRunner is used. There can be
only one ShellApplicationRunner but it can be redefined if needed for some reason.
Three ShellRunner implementation exists, named InteractiveShellRunner,
NonInteractiveShellRunner and ScriptShellRunner. These are enabled on default but
can be disable if needed using properties spring.shell.interactive.enabled,
spring.shell.noninteractive.enabled and spring.shell.script.enabled respecively.
9. Testing
Testing cli application is difficult due to various reasons:
-
There are differences between OS’s.
-
Within OS there may be different shell implementations in use.
-
What goes into a shell and comes out from a shell my be totally different what you see in shell itself due to control characters.
-
Shell may feel syncronous but most likely it is not meaning when someting is written into it, you can’t assume next update in in it is not final.
| Testing support is currently under development and will be unstable for various parts. |
9.1. Basics
Spring Shell provides a number of utilities and annotations to help when testing your application.
Test support is provided by two modules: spring-shell-test contains core items, and
spring-shell-test-autoconfigure supports auto-configuration for tests.
To test interactive commands.
@ShellTest
@DirtiesContext(classMode = ClassMode.AFTER_EACH_TEST_METHOD)
class InteractiveTestSample {
@Autowired
ShellTestClient client;
@Test
void test() {
InteractiveShellSession session = client
.interactive()
.run();
await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
ShellAssertions.assertThat(session.screen())
.containsText("shell");
});
session.write(session.writeSequence().text("help").carriageReturn().build());
await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
ShellAssertions.assertThat(session.screen())
.containsText("AVAILABLE COMMANDS");
});
}
}
To test non-interactive commands.
@ShellTest
@DirtiesContext(classMode = ClassMode.AFTER_EACH_TEST_METHOD)
class NonInteractiveTestSample {
@Autowired
ShellTestClient client;
@Test
void test() {
NonInteractiveShellSession session = client
.nonInterative("help", "help")
.run();
await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
ShellAssertions.assertThat(session.screen())
.containsText("AVAILABLE COMMANDS");
});
}
}