SHOUT User Manual

Introduction

Welcome to SHOUT, your AI-powered testing companion designed to simplify and enhance GUI test automation. This manual provides step-by-step instructions and best practices for using SHOUT effectively.

Installation

1. Download the SHOUT application from the official website.
2. Unpack the zip file.
3. Launch the SHOUT application.
4. Open the SHOUT web interface.

Settings

Edit settings.properties to add/change the following settings:

• gpt_key: GPT API key
• gpt_model (optional)
• gpt_assistant_model (optional)
• server_port: The port used by the SHOUT server.
• browser: Select Chrome, Firefox, Safari, or Edge.
• suite_folder: The folder name of the current suite.

Running SHOUT

Windows

Run (double-click) the run.bat file (no Java JDK needed since using the included JDK) or double-click the Shout.jar file (requires Java JDK 21 installed). You may need to unblock the run.bat file if it was downloaded.

Mac/Unix

Double-click the Shout.jar file (requires Java JDK 21 installed).

Accessing the Web Interface

Start the SHOUT web interface in a browser by navigating to localhost:5678 (default). This will open the dashboard where you can manage settings, tests, and suites.

Configuring Initial Settings

Navigate to the "Settings" page within the SHOUT interface and configure the following:

• Application URL: The full URL to the system under test (SUT). For example: https://michelnass.com/traveler/index.html.
• Suite Objective: Define the goal of the test suite, such as "Try booking different trips available from the Traveler website."
• Test Runner: Choose the runner for executing tests, such as "Similo" or "Agent". While Similo is the fastest option, using an Agent is more tolerant and may identify more defects.
• Target No Tests: Specify the number of tests to automatically create (e.g., 5) or set to 0 for manual test creation.
• Seconds Suite Delay: Set the interval in seconds between test suite runs. For instance, 0 for no delay.
• Seconds Test Delay: Define the delay between individual test executions within a suite. Set to 0 for no delay.
• Seconds Step Delay: Specify the delay between test steps. For example, 0 for instant execution.

Testing

Preparing the System

Before starting, ensure the application under test is accessible at the specified URL. If authentication is required, log in and accept any cookies. Alternatively, you can use a SetUp test to handle cookies or perform other setup actions automatically.

Saving Cookies

To avoid repeated logins during testing, use the "Save Cookies" button in the SHOUT interface. Saved cookies will be loaded automatically for future sessions.

Creating Tests

Automatically

SHOUT can automatically generate a series of tests based on the defined suite objective. This method leverages AI to understand the primary goals and create comprehensive test cases, saving time and reducing manual effort.

Exploratory

In exploratory testing, SHOUT autonomously navigates and interacts with the system under test (SUT). This mode is ideal for uncovering unexpected behaviors or exploring new functionalities without predefined scripts. The results from the exploratory session are automatically saved in the logs folder for further analysis.

Importing Manual Tests

Users can import existing test instructions into SHOUT. These can include high-level objectives or detailed step-by-step test cases. This option streamlines integration with previously defined test plans.

Cocreation

In cocreation, users work interactively with SHOUT to build test cases step-by-step. This collaborative approach combines AI insights with user knowledge, ensuring tailored and precise test scenarios.

SetUp Test

A SetUp test is a special type of test that can be used to prepare the environment or system under test before executing other tests in the suite. This ensures a consistent and controlled starting point for all subsequent tests.

To create a SetUp test, use the "Save as SetUp" button in the Cocreate interface. Once saved, the SetUp test will automatically run before all other tests in the suite if it is present.

Best practices for SetUp tests include:

• Logging into the application and saving the session state.
• Configuring any necessary system settings or parameters.
• Preparing test data required by subsequent tests.
• Dismissing cookies or pop-ups to streamline the test environment.

By leveraging SetUp tests, you can reduce the chances of failures caused by inconsistent or incomplete system states.

Commands

Accessing Commands

SHOUT supports commands via GET requests at localhost:5678/command. With these commands, you can ask the AI questions about the current test suite, request it to create or run tests, perform exploratory sessions, generate reports, receive advice, and perform other helpful tasks. Additionally, the dashboard page includes an input field where you can interact directly with the AI to issue these commands or ask questions in real-time.

Available Commands

• request: Ask the AI agent to answer a question, create a report, or perform an action.
• >>request: Similar to request but returns a raw response (useful for external integrations).
• run: Start executing all tests in the suite.
• stop: Halt ongoing test execution.
• kill: Terminate the SHOUT server.

Test Suite Data

Understanding the Suite Folder

All test-related data is stored in the "suite" folder. This includes:

• history: Backups of previous suite.json versions.
• logs: Execution logs, prompts, errors, and exploratory session outputs.
• media: Screenshots related to issues detected during testing.
• data.txt: Store application-specific details such as usernames, passwords, and workflows.
• stories.txt: Save user stories relevant to the testing process.
• suite.json: Defines the test suite structure, tests, steps, and issues. Only modify this file when SHOUT is not running.
• website.cookies: Saved cookies for seamless authentication.

Multiple Test Suites

Managing Multiple Suites

To manage multiple test suites, duplicate the "suite" folder. Update the suite_folder property in settings.properties to point to the desired folder.

Switching Between Suites

Ensure SHOUT is restarted after changing the suite_folder setting to apply the new configuration.