Refine #1323

- Encapsulate command name in ShellInputProvider
- Rename builder methods for better readability
- Update Javadocs
- Update reference docs
- Add missing headers

Issue #1292

Author: fmbenhassine

spring-shell-docs/modules/ROOT/pages/testing.adoc

@@ -69,6 +69,42 @@ class ShellTestIntegrationTests {
 }
 ----
 
+Spring Shell also provides the `ShellInputProvider` API which can be used to provide custom input for testing purposes. This allows you to simulate user input (clear texts and passwords) in a more flexible way.
+
+For example, if your command expects input as follows:
+
+[source,java]
+----
+@Bean
+public Command ask() {
+    return new AbstractCommand("ask", "Ask for user input") {
+        @Override
+        public ExitStatus doExecute(CommandContext commandContext) throws Exception {
+            String message = commandContext.inputReader().readInput();
+            commandContext.outputWriter().println("You said: " + message);
+            return ExitStatus.OK;
+        }
+    };
+}
+----
+
+then you can simulate the user's input by using `ShellInputProvider` to supply the necessary input during testing:
+
+[source,java]
+----
+@Test
+void testCommandExecutionWithReadingInput(@Autowired ShellTestClient client) throws Exception {
+    // given
+    ShellInputProvider inputProvider = ShellInputProvider.providerFor("ask").withInput("hi").build();
+
+    // when
+    ShellScreen screen = client.sendCommand(inputProvider);
+
+    // then
+    ShellAssertions.assertThat(screen).containsText("You said: hi");
+}
+----
+
 == End-to-End Testing
 
 For end-to-end (ie black-box) testing of shell applications without using Spring Shell testing facilities, you can use the test utilities provided by Spring Boot. Once you have defined your Spring Boot application class, you can create a test class annotated with `@SpringBootTest` to test your shell commands. Here is an example:

spring-shell-test/src/main/java/org/springframework/shell/test/ShellInputProvider.java

@@ -1,3 +1,18 @@
+/*
+ * Copyright 2026-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.springframework.shell.test;
 
 import java.util.ArrayList;
@@ -6,42 +21,57 @@
 import java.util.List;
 
 /**
- * Represents a provider for inputs and passwords used in shell interactions. This class
- * uses two {@link Deque} instances to manage the queue of user inputs and passwords. It
- * serves as a utility for simulating user input during testing or automated shell
- * interactions.
+ * Represents a provider for commands with their inputs and passwords used in shell
+ * interactions. This class uses two {@link Deque} instances to manage the queue of user
+ * inputs and passwords. It serves as a utility for simulating user input during testing
+ * or automated shell interactions.
  *
+ * @param command represents the command to be executed in the shell.
  * @param inputs Queue containing user input strings.
  * @param passwords Queue containing user password strings.
+ * @author David Pilar
+ * @author Mahmoud Ben Hassine
+ * @since 4.0.2
  */
-public record ShellInputProvider(Deque<String> inputs, Deque<String> passwords) {
+public record ShellInputProvider(String command, Deque<String> inputs, Deque<String> passwords) {
 
-	static Builder builder() {
-		return Builder.builder();
+	/**
+	 * Creates a new input provider for the specified command.
+	 * @param command the command for which the input provider is to be created
+	 * @return a new {@link Builder} instance initialized with the given command
+	 */
+	static Builder providerFor(String command) {
+		return Builder.builder(command);
 	}
 
 	final static class Builder {
 
+		private final String command;
+
 		private final List<String> inputs = new ArrayList<>();
 
 		private final List<String> passwords = new ArrayList<>();
 
-		static Builder builder() {
-			return new Builder();
+		Builder(String command) {
+			this.command = command;
+		}
+
+		static Builder builder(String command) {
+			return new Builder(command);
 		}
 
-		public Builder input(String... input) {
+		public Builder withInput(String... input) {
 			inputs.addAll(List.of(input));
 			return this;
 		}
 
-		public Builder password(String... password) {
+		public Builder withPassword(String... password) {
 			passwords.addAll(List.of(password));
 			return this;
 		}
 
 		public ShellInputProvider build() {
-			return new ShellInputProvider(new LinkedList<>(inputs), new LinkedList<>(passwords));
+			return new ShellInputProvider(command, new LinkedList<>(inputs), new LinkedList<>(passwords));
 		}
 
 	}

spring-shell-test/src/main/java/org/springframework/shell/test/ShellTestClient.java

@@ -16,7 +16,11 @@
 package org.springframework.shell.test;
 
 import org.springframework.shell.core.InputReader;
-import org.springframework.shell.core.command.*;
+import org.springframework.shell.core.command.CommandContext;
+import org.springframework.shell.core.command.CommandExecutor;
+import org.springframework.shell.core.command.CommandParser;
+import org.springframework.shell.core.command.CommandRegistry;
+import org.springframework.shell.core.command.ParsedInput;
 
 import java.io.PrintWriter;
 import java.io.StringWriter;
@@ -57,35 +61,36 @@ public ShellTestClient(CommandParser commandParser, CommandRegistry commandRegis
 	 * @throws Exception if an error occurred during command execution
 	 */
 	public ShellScreen sendCommand(String input) throws Exception {
-		return sendCommand(input, ShellInputProvider.builder().build());
+		return sendCommand(ShellInputProvider.providerFor(input).build());
 	}
 
 	/**
 	 * Sends a command to the shell, processes user inputs or passwords as needed, and
 	 * returns the resulting shell screen output.
-	 * @param input the raw command string to be sent to the shell
-	 * @param inputProvider a provider containing simulated user inputs and passwords
+	 * @param inputProvider a provider containing simulated user's command with inputs and
+	 * passwords
 	 * @return a {@code ShellScreen} object containing the output of the shell after
 	 * command execution
 	 * @throws Exception if an error occurs during the command execution
+	 * @since 4.0.2
 	 */
-	public ShellScreen sendCommand(String input, ShellInputProvider inputProvider) throws Exception {
+	public ShellScreen sendCommand(ShellInputProvider inputProvider) throws Exception {
 		StringWriter stringWriter = new StringWriter();
-		ParsedInput parsedInput = this.commandParser.parse(input);
+		ParsedInput parsedInput = this.commandParser.parse(inputProvider.command());
 		PrintWriter outputWriter = new PrintWriter(stringWriter);
 		InputReader inputReader = new InputReader() {
 			@Override
 			public String readInput(String prompt) {
 				outputWriter.print(prompt);
-				String in = inputProvider.inputs().pollFirst();
-				return in == null ? "" : in;
+				String input = inputProvider.inputs().pollFirst();
+				return input == null ? "" : input;
 			}
 
 			@Override
 			public char[] readPassword(String prompt) {
 				outputWriter.print(prompt);
-				String pwd = inputProvider.passwords().pollFirst();
-				return pwd == null ? new char[] {} : pwd.toCharArray();
+				String password = inputProvider.passwords().pollFirst();
+				return password == null ? new char[] {} : password.toCharArray();
 			}
 		};
 		CommandContext commandContext = new CommandContext(parsedInput, this.commandRegistry, outputWriter,

spring-shell-test/src/test/java/org/springframework/shell/test/ShellTestClientTests.java

@@ -1,3 +1,18 @@
+/*
+ * Copyright 2026-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.springframework.shell.test;
 
 import org.assertj.core.api.Assertions;
@@ -17,8 +32,6 @@
 import org.springframework.shell.core.command.ExitStatus;
 import org.springframework.test.context.junit.jupiter.SpringExtension;
 
-import java.io.PrintWriter;
-
 @ExtendWith(SpringExtension.class)
 class ShellTestClientTests {
 
@@ -40,17 +53,23 @@ void testUnknownCommandExecution(@Autowired ShellTestClient shellTestClient) {
 
 	@Test
 	void testCommandExecutionWithReadingInput(@Autowired ShellTestClient client) throws Exception {
+		// given
+		ShellInputProvider inputProvider = ShellInputProvider.providerFor("hello").withInput("hi").build();
+
 		// when
-		ShellScreen screen = client.sendCommand("hello", ShellInputProvider.builder().input("hi").build());
+		ShellScreen screen = client.sendCommand(inputProvider);
 
 		// then
 		ShellAssertions.assertThat(screen).containsText("You said: hi");
 	}
 
 	@Test
 	void testCommandExecutionWithReadingPassword(@Autowired ShellTestClient client) throws Exception {
+		// given
+		ShellInputProvider inputProvider = ShellInputProvider.providerFor("password").withPassword("secret123").build();
+
 		// when
-		ShellScreen screen = client.sendCommand("password", ShellInputProvider.builder().password("secret123").build());
+		ShellScreen screen = client.sendCommand(inputProvider);
 
 		// then
 		ShellAssertions.assertThat(screen).containsText("Your password is: secret123");
@@ -59,13 +78,13 @@ void testCommandExecutionWithReadingPassword(@Autowired ShellTestClient client)
 	@Test
 	void testCommandExecutionWithComplexInputs(@Autowired ShellTestClient client) throws Exception {
 		// given
-		ShellInputProvider inputProvider = ShellInputProvider.builder()
-			.input("One", "Two")
-			.password("secret1", "secret2")
+		ShellInputProvider inputProvider = ShellInputProvider.providerFor("complex")
+			.withInput("One", "Two")
+			.withPassword("secret1", "secret2")
 			.build();
 
 		// when
-		ShellScreen screen = client.sendCommand("complex", inputProvider);
+		ShellScreen screen = client.sendCommand(inputProvider);
 
 		// then
 		ShellAssertions.assertThat(screen).containsText("First input is: One");