Add base shell test system

- NOTE: very much wip and unstable
- This commit is a first step to provide boot style
  @ShellTest annotation
- New modules spring-shell-test and spring-shell-test-autoconfigure
- Focus is to autoconfigure context without shell runners so that
  we can create "sessions" and hook to configures jline terminal
  with custom in/out streams.
- Skeleton fork from jediterm to provide basic terminal emulation
  to part of a control amd escape characters working.
- ShellTestClient is a concept user can use to interact with a shell
  in a same way user would use a "real" shell.
- Fixes #489

Author: jvalkeal

settings.gradle

@@ -49,6 +49,8 @@ include 'spring-shell-samples'
 include 'spring-shell-standard'
 include 'spring-shell-standard-commands'
 include 'spring-shell-table'
+include 'spring-shell-test'
+include 'spring-shell-test-autoconfigure'
 
 file("${rootDir}/spring-shell-starters").eachDirMatch(~/spring-shell-starter.*/) {
 	include "spring-shell-starters:${it.name}"

spring-shell-docs/spring-shell-docs.gradle

@@ -7,7 +7,9 @@ description = 'Spring Shell Documentation'
 dependencies {
 	management platform(project(":spring-shell-management"))
 	implementation project(':spring-shell-starters:spring-shell-starter')
+	implementation project(':spring-shell-starters:spring-shell-starter-test')
 	testImplementation 'org.springframework.boot:spring-boot-starter-test'
+	testImplementation 'org.awaitility:awaitility'
 }
 
 asciidoctorj {

spring-shell-docs/src/main/asciidoc/using-shell-testing-basics.adoc

@@ -0,0 +1,25 @@
+[[using-shell-testing-basics]]
+==== Basics
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+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.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/TestingSnippets.java[tag=testing-shelltest-interactive]
+----
+====
+
+To test _non-interactive_ commands.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/TestingSnippets.java[tag=testing-shelltest-noninteractive]
+----
+====

spring-shell-docs/src/main/asciidoc/using-shell-testing.adoc

@@ -0,0 +1,18 @@
+[[using-shell-testing]]
+== Testing
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+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.
+
+NOTE: Testing support is currently under development and will be
+      unstable for various parts.
+
+include::using-shell-testing-basics.adoc[]

spring-shell-docs/src/main/asciidoc/using-shell.adoc

@@ -13,3 +13,5 @@ include::using-shell-components.adoc[]
 include::using-shell-customization.adoc[]
 
 include::using-shell-execution.adoc[]
+
+include::using-shell-testing.adoc[]

spring-shell-docs/src/test/java/org/springframework/shell/docs/TestingSnippets.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2022 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.docs;
+
+import java.util.concurrent.TimeUnit;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.shell.test.ShellAssertions;
+import org.springframework.shell.test.ShellTestClient;
+import org.springframework.shell.test.ShellTestClient.InteractiveShellSession;
+import org.springframework.shell.test.ShellTestClient.NonInteractiveShellSession;
+import org.springframework.shell.test.autoconfigure.ShellTest;
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.annotation.DirtiesContext.ClassMode;
+
+import static org.awaitility.Awaitility.await;
+
+class TestingSnippets {
+
+	// tag::testing-shelltest-interactive[]
+	@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");
+			});
+		}
+	}
+	// end::testing-shelltest-interactive[]
+
+	// tag::testing-shelltest-noninteractive[]
+	@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");
+			});
+		}
+	}
+	// end::testing-shelltest-noninteractive[]
+}

spring-shell-samples/spring-shell-samples.gradle

@@ -9,7 +9,9 @@ description = 'Spring Shell Samples'
 dependencies {
 	management platform(project(":spring-shell-management"))
 	implementation project(':spring-shell-starters:spring-shell-starter-jna')
+	testImplementation project(':spring-shell-starters:spring-shell-starter-test')
 	testImplementation 'org.springframework.boot:spring-boot-starter-test'
+	testImplementation 'org.awaitility:awaitility'
 }
 
 springBoot {

spring-shell-samples/src/test/java/org/springframework/shell/samples/AbstractSampleTests.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2022 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.samples;
+
+import java.util.concurrent.TimeUnit;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Import;
+import org.springframework.shell.samples.standard.ResolvedCommands;
+import org.springframework.shell.test.ShellAssertions;
+import org.springframework.shell.test.ShellTestClient;
+import org.springframework.shell.test.ShellTestClient.BaseShellSession;
+import org.springframework.shell.test.ShellTestClient.InteractiveShellSession;
+import org.springframework.shell.test.ShellTestClient.NonInteractiveShellSession;
+import org.springframework.shell.test.autoconfigure.ShellTest;
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.annotation.DirtiesContext.ClassMode;
+
+import static org.awaitility.Awaitility.await;
+
+@ShellTest
+@Import(ResolvedCommands.ResolvedCommandsConfiguration.class)
+@DirtiesContext(classMode = ClassMode.AFTER_EACH_TEST_METHOD)
+public class AbstractSampleTests {
+
+	@Autowired
+	protected ShellTestClient client;
+
+	protected void assertScreenContainsText(BaseShellSession<?> session, String text) {
+		await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
+			ShellAssertions.assertThat(session.screen()).containsText(text);
+		});
+	}
+
+	protected BaseShellSession<?> createSession(String command, boolean interactive) {
+		if (interactive) {
+			InteractiveShellSession session = client.interactive().run();
+			session.write(session.writeSequence().command(command).build());
+			return session;
+		}
+		else {
+			String[] commands = command.split(" ");
+			NonInteractiveShellSession session = client.nonInterative(commands).run();
+			return session;
+		}
+	}
+}

spring-shell-samples/src/test/java/org/springframework/shell/samples/e2e/RequiredValueCommandsTests.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2022 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.samples.e2e;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+import org.springframework.shell.samples.AbstractSampleTests;
+import org.springframework.shell.test.ShellTestClient.BaseShellSession;
+
+class RequiredValueCommandsTests extends AbstractSampleTests {
+
+	@ParameterizedTest
+	@CsvSource({
+		"e2e anno required-value,false",
+		"e2e reg required-value,false",
+		"e2e anno required-value,true",
+		"e2e reg required-value,true"
+	})
+	void shouldRequireOption(String command, boolean interactive) {
+		BaseShellSession<?> session = createSession(command, interactive);
+		assertScreenContainsText(session, "Missing mandatory option");
+	}
+}

spring-shell-samples/src/test/java/org/springframework/shell/samples/standard/ComponentCommandsTests.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2022 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.samples.standard;
+
+import java.util.concurrent.TimeUnit;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+import org.springframework.shell.samples.AbstractSampleTests;
+import org.springframework.shell.test.ShellAssertions;
+import org.springframework.shell.test.ShellTestClient.BaseShellSession;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
+
+public class ComponentCommandsTests extends AbstractSampleTests {
+
+	@ParameterizedTest
+	@CsvSource({
+		"component single,false",
+		"component single,true"
+	})
+	void componentSingle(String command, boolean interactive) {
+		BaseShellSession<?> session = createSession(command, interactive);
+
+		await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
+			assertThat(session.screen().lines()).anySatisfy(line -> {
+				assertThat(line).containsPattern("[>❯] key1");
+			});
+		});
+
+		session.write(session.writeSequence().keyDown().build());
+		await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
+			assertThat(session.screen().lines()).anySatisfy(line -> {
+				assertThat(line).containsPattern("[>❯] key2");
+			});
+		});
+
+		session.write(session.writeSequence().cr().build());
+		await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
+			ShellAssertions.assertThat(session.screen()).containsText("Got value value2");
+		});
+	}
+
+	@ParameterizedTest
+	@CsvSource({
+		"component multi,false",
+		"component multi,true"
+	})
+	void componentMulti(String command, boolean interactive) {
+		BaseShellSession<?> session = createSession(command, interactive);
+
+		await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
+			assertThat(session.screen().lines()).anySatisfy(line -> {
+				assertThat(line).containsPattern("[>❯] (☐|\\[ \\])  key1");
+			});
+		});
+
+		session.write(session.writeSequence().space().build());
+		await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
+			assertThat(session.screen().lines()).anySatisfy(line -> {
+				assertThat(line).containsPattern("[>❯] (☒|\\[x\\])  key1");
+			});
+		});
+
+		session.write(session.writeSequence().cr().build());
+		await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
+			ShellAssertions.assertThat(session.screen()).containsText("Got value value1,value2");
+		});
+	}
+}

spring-shell-starters/spring-shell-starter-test/spring-shell-starter-test.gradle

@@ -0,0 +1,12 @@
+plugins {
+	id 'org.springframework.shell.starter'
+}
+
+description = 'Spring Shell Starter Test'
+
+dependencies {
+	management platform(project(":spring-shell-management"))
+	api(project(':spring-shell-starters:spring-shell-starter'))
+	api(project(":spring-shell-test"))
+	api(project(":spring-shell-test-autoconfigure"))
+}

spring-shell-test-autoconfigure/spring-shell-test-autoconfigure.gradle

@@ -0,0 +1,21 @@
+plugins {
+	id 'org.springframework.shell.module'
+}
+
+description = 'Spring Shell Test Autoconfigure'
+
+dependencies {
+	management platform(project(":spring-shell-management"))
+	implementation project(':spring-shell-core')
+	implementation project(':spring-shell-standard')
+	implementation project(':spring-shell-test')
+	implementation project(':spring-shell-autoconfigure')
+	implementation 'org.springframework:spring-test'
+	implementation 'org.springframework.boot:spring-boot-autoconfigure'
+	implementation 'org.springframework.boot:spring-boot-test-autoconfigure'
+	implementation 'org.springframework.boot:spring-boot-starter-test'
+	optional 'org.jline:jline'
+	optional 'org.assertj:assertj-core'
+	optional 'org.junit.jupiter:junit-jupiter-api'
+	testImplementation 'org.awaitility:awaitility'
+}