### Setting up Directory for Workspace Example Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Creates a directory named `workspace_dir` and a file `test_file.txt` inside it. This setup is used to demonstrate running specdown commands within a specific workspace directory. ```shell mkdir workspace_dir echo "file in workspace dir" >workspace_dir/test_file.txt ``` -------------------------------- ### Specdown Markdown File (Invalid Shell Command Example Start) Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md The beginning of an example markdown file intended to demonstrate an invalid shell command error, though the specific invalid command is not shown in this snippet. ```markdown # ``` -------------------------------- ### Getting Help for a Sub-command Source: https://github.com/specdown/specdown/blob/master/docs/cli/display_help.md Illustrates how to retrieve specific help documentation for a SpecDown sub-command by appending the `--help` flag, using the `strip` command as an example. ```shell specdown strip --help ``` -------------------------------- ### Create Working Directory and File (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Creates a directory structure `workspace/working_dir` and writes "Message Example" into `workspace/working_dir/message.txt`. This sets up files for the working directory example. ```shell mkdir -p workspace/working_dir echo "Message Example" >workspace/working_dir/message.txt ``` -------------------------------- ### Example Markdown Specification File Content Source: https://github.com/specdown/specdown/blob/master/README.md This block contains the full markdown content of an example specification file (`example.md`) used to demonstrate SpecDown. It includes nested code blocks for execution and verification. ```markdown ## This document is an executable specification When SpecDown is run with this document, it will execute the following shell script. ```shell,script(name="hello-specdown") echo "Hello SpecDown" ``` It will then validate that the previous command's output matches the following codeblock. ```,verify(script_name="hello-specdown", stream=stdout) Hello SpecDown ``` ``` -------------------------------- ### Example markdown file with shell script (Markdown) Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Defines a markdown file content (`missing_shell_example.md`) containing a simple shell script block that prints 'Hello world'. ```markdown # Hello World ```shell,script(name="test") echo "Hello world" ``` ``` -------------------------------- ### Running Specdown with Skipped Block Example Source: https://github.com/specdown/specdown/blob/master/docs/specs/skipping_code_blocks.md Executes the `specdown run` command on the `skip_example.md` file. The `script` tag names the execution and expects a successful exit code. ```shell specdown run skip_example.md ``` -------------------------------- ### Install SpecDown on Linux via Homebrew Source: https://github.com/specdown/specdown/blob/master/README.md This shell command uses Homebrew (installed on Linux) to install SpecDown. The `skip()` directive prevents SpecDown from executing this block during a test run. ```shell brew install specdown/homebrew-repo/specdown ``` -------------------------------- ### Install SpecDown on Linux via Direct Download Source: https://github.com/specdown/specdown/blob/master/README.md These shell commands download the latest SpecDown binary for Linux (x86_64) and make it executable. The `skip()` directive prevents SpecDown from executing this block during a test run. ```shell curl -L https://github.com/specdown/specdown/releases/latest/download/specdown-x86_64-unknown-linux-gnu -o /usr/local/bin/specdown chmod +x /usr/local/bin/specdown ``` -------------------------------- ### Install SpecDown on macOS via Direct Download Source: https://github.com/specdown/specdown/blob/master/README.md These shell commands download the latest SpecDown binary for macOS (x86_64) and make it executable. The `skip()` directive prevents SpecDown from executing this block during a test run. ```shell curl -L https://github.com/specdown/specdown/releases/latest/download/specdown-x86_64-apple-darwin -o /usr/local/bin/specdown chmod +x /usr/local/bin/specdown ``` -------------------------------- ### Install SpecDown on macOS via Homebrew Source: https://github.com/specdown/specdown/blob/master/README.md This shell command uses the Homebrew package manager to install SpecDown on macOS. The `skip()` directive prevents SpecDown from executing this block during a test run. ```shell brew install specdown/homebrew-repo/specdown ``` -------------------------------- ### Specdown Verification Example Output Text Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Shows the expected console output when running the `verify_example.md` Specdown file. It details the results of each function (script execution and verification), indicating which passed (stdout verification) and which failed (stderr verification), including a diff showing the discrepancy. ```text Running tests for verify_example.md: ✓ running script 'stdout_and_stderr' succeeded ✓ verifying stdout from 'stdout_and_stderr' succeeded ✗ verifying stderr from 'stdout_and_stderr' failed === < expected / > actual Bad stderr === 3 functions run (2 succeeded / 1 failed) ``` -------------------------------- ### Install SpecDown on Windows via PowerShell Source: https://github.com/specdown/specdown/blob/master/README.md This PowerShell command downloads the latest SpecDown executable for Windows (x86_64) using Invoke-WebRequest. The `skip()` directive prevents SpecDown from executing this block during a test run. ```powershell Invoke-WebRequest -Uri "https://github.com/specdown/specdown/releases/latest/download/specdown-x86_64-pc-windows-msvc.exe" -OutFile "specdown.exe" ``` -------------------------------- ### Specdown Markdown File Verifying Unknown Script Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Example markdown file (`verify_unknown_script_example.md`) containing a `verify()` function annotation that attempts to verify the output of a script named "unknown", which has not been defined or executed, causing a runtime error. ```markdown # Verify Unknown Script Example\n\n\`\`\`text,verify(script_name="unknown")\nThis doesn't matter\n\`\`\` ``` -------------------------------- ### Defining Script in First Multiple Spec File Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Defines a simple shell script (`command_1`) in the `example-file1.md` specdown Markdown file as part of the example for running multiple files. ```shell echo "Spec 1" ``` -------------------------------- ### Defining Script in Second Multiple Spec File Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Defines a simple shell script (`command_2`) in the `example-file2.md` specdown Markdown file as part of the example for running multiple files. ```shell echo "Spec 2" ``` -------------------------------- ### Example Markdown File with Skipped Block Source: https://github.com/specdown/specdown/blob/master/docs/specs/skipping_code_blocks.md Defines a markdown file named `skip_example.md` containing a code block marked with `test,skip()` to prevent specdown execution. ```markdown # Skipping Code Blocks Example ```test,skip() This codeblock is not executed ``` ``` -------------------------------- ### Running Specdown Verification Example Shell Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Executes the Specdown test file `verify_example.md` using the `specdown run` command. The `expected_exit_code=1` argument indicates that the test run itself is expected to exit with a non-zero status code, which occurs because one of the verification steps within the file is designed to fail. ```shell specdown run verify_example.md ``` -------------------------------- ### Run Spec with Workspace Init Command (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Executes a specdown test file (`init_workspace_test.md`). It uses `--temporary-workspace-dir` to create a temporary workspace and `--workspace-init-command` to run a command (`echo "Message from workspace root" >message.txt`) within the workspace before tests start. Expects exit code 0. ```shell specdown run \n --temporary-workspace-dir \n --workspace-init-command 'echo "Message from workspace root" >message.txt' \n init_workspace_test.md ``` -------------------------------- ### Specdown Markdown File with Unknown Function Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Example markdown file (`unknown_function_example.md`) containing a shell code block annotated with an unknown `function()` specdown function, which will cause a parsing error. ```markdown # Unknown Function Example\n\n\`\`\`shell,function()\necho "This script is annotated with an unknown function"\n\`\`\` ``` -------------------------------- ### Run Specdown Test with --temporary-workspace-dir to Demonstrate SPECDOWN_START_DIR Source: https://github.com/specdown/specdown/blob/master/docs/specs/global_environment_variables.md This command runs the `check_file_in_start_dir.md` spec file using a temporary workspace directory. This setup is used to demonstrate that the script inside the spec file can still access files in the original start directory using `SPECDOWN_START_DIR`, even when the working directory is temporary. ```shell specdown run --temporary-workspace-dir check_file_in_start_dir.md ``` -------------------------------- ### Specdown Omit Name Example Output Text Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Shows the expected console output when running the `omit_name_example.md` Specdown file. It confirms that all functions (script executions and verifications for both unnamed and named scripts) succeeded, resulting in a successful test run. ```text Running tests for omit_name_example.md: ✓ running script '' succeeded ✓ verifying stdout from '' succeeded ✓ running script 'script_with_name' succeeded ✓ verifying stdout from 'script_with_name' succeeded 4 functions run (4 succeeded / 0 failed) ``` -------------------------------- ### Get Shell Name (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md This shell script is defined within the `setting_the_shell_example.md` spec file. It uses `basename "$0"` to get the name of the currently executing shell. ```shell basename "$0" ``` -------------------------------- ### Specdown Markdown File with Missing Function Argument Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Example markdown file (`missing_function_argument_example.md`) containing a shell code block annotated with the `file()` specdown function but missing the required `path` argument, which will cause a parsing error. ```markdown # Unknown Function Example\n\n\`\`\`shell,file()\nThis file has no path!\n\`\`\` ``` -------------------------------- ### Running Specdown Omit Name Example Shell Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Executes the Specdown test file `omit_name_example.md` using the `specdown run` command. The `expected_exit_code=0` argument indicates that this test run is expected to complete successfully, as all script executions and verification steps within the file are designed to pass. ```shell specdown run omit_name_example.md ``` -------------------------------- ### Specdown Markdown File with Invalid Argument Option Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Example markdown file (`invalid_token_option_example.md`) containing a `verify()` function annotation where the `stream` argument is given an invalid value (`unknown`) instead of one of the allowed options (`output`, `stdout`, `stderr`), causing a parsing error. ```markdown # Unknown Function Example\n\n\`\`\`shell,script(name="script")\necho "This script will work"\n\`\`\`\n\n\`\`\`text,verify(script_name="script", stream=unknown)\nunknown is not a valid stream\n\`\`\` ``` -------------------------------- ### Example Embedded Shell Script in Specdown Markdown Source: https://github.com/specdown/specdown/blob/master/docs/cli/stripping_specs.md This is a simple shell script embedded within a specdown markdown file using the `script` function. It demonstrates a basic command that will be executed by specdown when processing the file. ```shell echo "Hello world" ``` -------------------------------- ### Specdown Markdown File with Invalid Argument Type Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Example markdown file (`invalid_argument_value_example.md`) containing a shell code block annotated with the `script()` specdown function where the `name` argument is provided as an integer (`123`) instead of the required string type, causing a parsing error. ```markdown # Unknown Function Example\n\n\`\`\`shell,script(name=123)\necho "This script has an integer name"\n\`\`\` ``` -------------------------------- ### Running a SpecDown Specification File Source: https://github.com/specdown/specdown/blob/master/README.md This shell command executes SpecDown with the `run` command, specifying the `example.md` file as the input specification. SpecDown will process the code blocks within that file. ```shell specdown run example.md ``` -------------------------------- ### Verifying Script Stderr Specdown Text Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Verifies the standard error of the "stdout_and_stderr" script using Specdown's `verify` function with the `stream=stderr` argument. The expected output is the literal text "Good stderr". This block is placed after the stdout verification in the Specdown markdown file and is shown to fail in the example output. ```text Good stderr ``` -------------------------------- ### Running specdown Test File with Shell Source: https://github.com/specdown/specdown/blob/master/docs/specs/creating_test_files.md Provides the shell command to execute the specdown test file `writing_file_example.md`. This command triggers the processing of the spec file, including creating temporary files and running scripts defined within it. ```shell specdown run writing_file_example.md ``` -------------------------------- ### Running SpecDown without arguments Source: https://github.com/specdown/specdown/blob/master/docs/cli/display_help.md Demonstrates how executing the `specdown` command without any additional arguments displays the main help message for the tool. ```shell specdown ``` -------------------------------- ### Run Spec with Workspace and Working Directory (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Executes the `working_dir_example.md` spec file. It uses `--workspace-dir workspace` to set the workspace root and `--working-dir working_dir` to set the directory where scripts within the spec will run. Expects exit code 0. ```shell specdown run --workspace-dir workspace --working-dir working_dir working_dir_example.md ``` -------------------------------- ### Verifying specdown Run Output with Text Source: https://github.com/specdown/specdown/blob/master/docs/specs/creating_test_files.md Shows the expected standard output when running the `specdown run writing_file_example.md` command. This output confirms that the tests defined in the spec file, including file creation and script execution, passed successfully. ```text Running tests for writing_file_example.md: ✓ creating file example.txt succeeded ✓ running script 'cat-file' succeeded ✓ verifying stdout from 'cat-file' succeeded 3 functions run (3 succeeded / 0 failed) ``` -------------------------------- ### Displaying specdown run Help (Windows) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md This snippet shows the help output for the `specdown run` command on Windows operating systems, detailing its usage, arguments, and available options for configuring spec execution. Note that the output is identical to the non-Windows version in this case. ```text Runs a given Markdown Specification Usage: specdown run [OPTIONS] [SPEC_FILES]... Arguments: [SPEC_FILES]... The spec files to run Options: --workspace-dir Set the workspace directory --temporary-workspace-dir Create a temporary workspace directory --working-dir The directory where commands will be executed. This is relative to the workspace dir --workspace-init-command A command to run in the workspace before running the specs --shell-command The shell command used to execute script blocks [default: "bash -c"] --env Set an environment variable (format: 'VAR_NAME=value') --unset-env Unset an environment variable --add-path Adds the given directory to PATH -h, --help Print help ``` -------------------------------- ### Creating File Content with specdown Text Source: https://github.com/specdown/specdown/blob/master/docs/specs/creating_test_files.md Defines the content for a temporary file `example.txt` using the `text,file` specdown function. This file is created within the context of a larger spec file being processed. ```text Example file content ``` -------------------------------- ### Empty Specdown Markdown File (for Shell Command Test) Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md A minimal markdown file (`empty_shell_command_example.md`) containing only a title, used as a placeholder for testing errors related to the `--shell-command` argument in `specdown run`. ```markdown # Nothing to see here ``` -------------------------------- ### Verifying Script Output with specdown Text Source: https://github.com/specdown/specdown/blob/master/docs/specs/creating_test_files.md Specifies the expected standard output for the `cat-file` script using the `text,verify` specdown function. This verifies that the script successfully read the content of `example.txt`. ```text Example file content ``` -------------------------------- ### Displaying specdown run Help (Non-Windows) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md This snippet shows the help output for the `specdown run` command on non-Windows operating systems, detailing its usage, arguments, and available options for configuring spec execution. ```text Runs a given Markdown Specification Usage: specdown run [OPTIONS] [SPEC_FILES]... Arguments: [SPEC_FILES]... The spec files to run Options: --workspace-dir Set the workspace directory --temporary-workspace-dir Create a temporary workspace directory --working-dir The directory where commands will be executed. This is relative to the workspace dir --workspace-init-command A command to run in the workspace before running the specs --shell-command The shell command used to execute script blocks [default: "bash -c"] --env Set an environment variable (format: 'VAR_NAME=value') --unset-env Unset an environment variable --add-path Adds the given directory to PATH -h, --help Print help ``` -------------------------------- ### Run Spec with Default Shell (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Executes the `setting_the_shell_example.md` spec file using the default shell (`bash`). This run is expected to succeed. Expects exit code 0. ```shell specdown run setting_the_shell_example.md ``` -------------------------------- ### Running a Single Specdown File Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Executes a single specdown Markdown file (`example-spec.md`) using the `specdown run` command. This command discovers and runs all scripts and verification blocks within the specified file. ```shell specdown run example-spec.md ``` -------------------------------- ### Running Specdown Test File (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_exit_codes.md Executes the `exit_example.md` file using the `specdown run` command. This command triggers the execution and verification of the scripts defined within the markdown file. ```shell specdown run exit_example.md ``` -------------------------------- ### SpecDown Main Help Output (Windows) Source: https://github.com/specdown/specdown/blob/master/docs/cli/display_help.md Displays the standard error output produced by running `specdown` without arguments on Windows systems, showing the general usage, commands, and options. The output is similar to non-Windows but might have minor differences. ```text A tool to test markdown files and drive development from documentation. Usage: specdown [OPTIONS] Commands: completion Output completion for a shell of your choice run Runs a given Markdown Specification strip Outputs a version of the markdown with all specdown functions removed help Print this message or the help of the given subcommand(s) Options: --no-colour Disables coloured output -h, --help Print help -V, --version Print version ``` -------------------------------- ### Executing Shell Script to Read File with specdown Source: https://github.com/specdown/specdown/blob/master/docs/specs/creating_test_files.md Defines a shell script named `cat-file` that uses the `cat` command to read the content of the previously created `example.txt` file. This script is executed by specdown. ```shell cat example.txt ``` -------------------------------- ### Running Spec with --temporary-workspace-directory Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Creates a file `missing-file.txt` in the current directory and then runs the `temporary_workspace_dir_example.md` spec using `specdown run` with the `--temporary-workspace-directory` argument. This ensures the spec runs in a clean, temporary directory where the created file does not exist. ```shell echo "this file is in the current workspace directory" >missing-file.txt specdown run --temporary-workspace-dir temporary_workspace_dir_example.md ``` -------------------------------- ### Display Completion Command Help Source: https://github.com/specdown/specdown/blob/master/docs/cli/completion.md This command displays the help message for the `specdown completion` subcommand, showing available options and supported shells. ```shell specdown completion --help ``` -------------------------------- ### Run Specdown Verifying Unknown Script File Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Shell command to execute the `specdown run` command on the `verify_unknown_script_example.md` file, expected to fail because the `verify()` function attempts to reference a script name ("unknown") that does not exist. The `expected_exit_code=2` indicates an expected failure. ```shell specdown run verify_unknown_script_example.md ``` -------------------------------- ### Verifying UTF-8 Output with specdown Text Source: https://github.com/specdown/specdown/blob/master/docs/specs/creating_test_files.md Specifies the expected standard output for the `unicode_example` script using the `text,verify` specdown function. This verifies that the UTF-8 character was correctly echoed by the script. ```text ✓ ``` -------------------------------- ### Running Multiple Specdown Files Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Executes multiple specdown Markdown files (`example-file1.md` and `example-file2.md`) simultaneously using the `specdown run` command by listing them as arguments. ```shell specdown run example-file1.md example-file2.md ``` -------------------------------- ### SpecDown Strip Sub-command Help Output Source: https://github.com/specdown/specdown/blob/master/docs/cli/display_help.md Shows the expected output when requesting help for the `specdown strip` sub-command, detailing its usage, arguments, and options. ```text Outputs a version of the markdown with all specdown functions removed Usage: specdown strip Arguments: The spec file to strip specdown functions from Options: -h, --help Print help ``` -------------------------------- ### Run Specdown with Unknown Function File Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Shell command to execute the `specdown run` command on the `unknown_function_example.md` file, expected to fail due to the unknown function annotation. The `expected_exit_code=1` indicates an expected failure. ```shell specdown run unknown_function_example.md ``` -------------------------------- ### Running specdown with non-existent shell command (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Demonstrates running the `specdown run` command with a `--shell-command` argument that specifies a non-existent program, expected to fail with exit code 2. ```shell specdown run --shell-command 'does-not-exist' missing_shell_example.md ``` -------------------------------- ### SpecDown Main Help Output (Non-Windows) Source: https://github.com/specdown/specdown/blob/master/docs/cli/display_help.md Displays the standard error output produced by running `specdown` without arguments on non-Windows systems, showing the general usage, commands, and options. ```text A tool to test markdown files and drive development from documentation. Usage: specdown [OPTIONS] Commands: completion Output completion for a shell of your choice run Runs a given Markdown Specification strip Outputs a version of the markdown with all specdown functions removed help Print this message or the help of the given subcommand(s) Options: --no-colour Disables coloured output -h, --help Print help -V, --version Print version ``` -------------------------------- ### Displaying Help for Specdown Strip Command (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/stripping_specs.md This command executes the `specdown strip` subcommand with the `--help` flag to display the command-line options and usage information. The output varies slightly between Windows and non-Windows operating systems, as shown in the subsequent text blocks. ```shell specdown strip --help ``` -------------------------------- ### Defining OS Specific Negation Test File (Markdown) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Defines the content of the `os_specific_negation.md` file. This file includes a script block and two verification blocks, one using `target_os="!windows"` to verify output on any OS *except* Windows, and another for Windows. ```markdown # OS Specific nagative verifiction Run a script with no name: ```shell,script(name="os_specific_negation") specdown -h ``` Verify the output: ```text,verify(script_name="os_specific_negation",target_os="!windows") A tool to test markdown files and drive development from documentation. Usage: specdown [OPTIONS] Commands: completion Output completion for a shell of your choice run Runs a given Markdown Specification strip Outputs a version of the markdown with all specdown functions removed help Print this message or the help of the given subcommand(s) Options: --no-colour Disables coloured output -h, --help Print help -V, --version Print version ``` ```text,verify(script_name="os_specific_negation",target_os="windows") A tool to test markdown files and drive development from documentation. Usage: specdown.exe [OPTIONS] Commands: completion Output completion for a shell of your choice run Runs a given Markdown Specification strip Outputs a version of the markdown with all specdown functions removed help Print this message or the help of the given subcommand(s) Options: --no-colour Disables coloured output -h, --help Print help -V, --version Print version ``` ~~~ ``` -------------------------------- ### Running Spec with --workspace-dir Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Executes the `workspace_dir_example.md` spec using `specdown run` and the `--workspace-dir` argument to set the workspace directory to `workspace_dir`. This ensures scripts within the spec run relative to this directory. ```shell specdown run --workspace-dir workspace_dir workspace_dir_example.md ``` -------------------------------- ### Run specdown Verifying Unknown Script - shell Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Executes the `specdown run` command on the `verify_unknown_script_example.md` file, expecting an exit code of 2 because the script to be verified does not exist, resulting in a runtime error. ```shell specdown run verify_unknown_script_example.md ``` -------------------------------- ### Run Specdown with Missing Function Argument File Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Shell command to execute the `specdown run` command on the `missing_function_argument_example.md` file, expected to fail because the `file()` function annotation is missing the required `path` argument. The `expected_exit_code=1` indicates an expected failure. ```shell specdown run missing_function_argument_example.md ``` -------------------------------- ### Output of Running Single Specdown File Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Shows the expected console output when running `specdown run example-spec.md`. It indicates that the scripts and verification steps within the file were executed successfully. ```text Running tests for example-spec.md: ✓ running script 'command_1' succeeded ✓ verifying stdout from 'command_1' succeeded 2 functions run (2 succeeded / 0 failed) ``` -------------------------------- ### Define Empty Shell Command Spec File - specdown Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Defines a simple markdown file (`empty_shell_command_example.md`) with minimal content, used to demonstrate the error that occurs when an empty string is provided as the shell command. ```markdown # Nothing to see here ``` -------------------------------- ### Expected Output from Running SpecDown Source: https://github.com/specdown/specdown/blob/master/README.md This block shows the expected standard output (`stdout`) when running SpecDown on the `example.md` file. It indicates the test results for the embedded scripts and verifications. ```text Running tests for example.md: ✓ running script 'hello-specdown' succeeded ✓ verifying stdout from 'hello-specdown' succeeded 2 functions run (2 succeeded / 0 failed) ``` -------------------------------- ### Run Spec with SH Shell (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Executes the `setting_the_shell_example.md` spec file, explicitly setting the shell command to `sh -c` using `--shell-command`. This run is expected to fail because the spec verifies for `bash`. Expects exit code 1. ```shell ``` -------------------------------- ### Load Fish Completion Script Source: https://github.com/specdown/specdown/blob/master/docs/cli/completion.md This command generates the Fish completion script and redirects its output to the standard Fish completions directory, making it available for the Fish shell. ```shell specdown completion fish > ~/.config/fish/completions/specdown.fish ``` -------------------------------- ### Verifying Shell Script Output in Specdown Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Verifies the standard output of a previously defined script (`command_1`) using a `text,verify` code block. It checks if the output matches the expected text "Hello world". ```text Hello world ``` -------------------------------- ### Defining Basic Shell Script in Specdown Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Defines a simple shell script within a specdown Markdown file using a `shell,script` code block. This script prints "Hello world" to standard output. ```shell echo "Hello world" ``` -------------------------------- ### Run Specdown with Invalid Argument Option File Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Shell command to execute the `specdown run` command on the `invalid_token_option_example.md` file, expected to fail because the `verify()` function annotation uses an invalid value for the `stream` argument. The `expected_exit_code=1` indicates an expected failure. ```shell specdown run invalid_token_option_example.md ``` -------------------------------- ### Expected Output from Specdown Run Source: https://github.com/specdown/specdown/blob/master/docs/specs/skipping_code_blocks.md Shows the expected output when running specdown on `skip_example.md`. It confirms that no functions were run, indicating the code block was successfully skipped. ```text Running tests for skip_example.md: 0 functions run (0 succeeded / 0 failed) ``` -------------------------------- ### Define Markdown File Verifying Unknown Script - specdown Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Defines a markdown file (`verify_unknown_script_example.md`) containing a `verify` block that attempts to verify the output of a script named "unknown" which has not been executed, demonstrating a runtime error. ```markdown # Verify Unknown Script Example ```text,verify(script_name="unknown") This doesn't matter ``` ``` -------------------------------- ### Verify Message File Content (Text) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md This text block is defined within the `working_dir_example.md` spec file. It serves as the expected output for the preceding `cat message.txt` script. ```text Message Example ``` -------------------------------- ### Run specdown with Missing Argument File - shell Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Executes the `specdown run` command on the `missing_function_argument_example.md` file, expecting an exit code of 1 due to the missing function argument error detected during parsing. ```shell specdown run missing_function_argument_example.md ``` -------------------------------- ### Verifying OS Specific Negation Test Run Output (Text) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Defines the expected standard output after successfully running the `os_specific_negation.md` test file. This block verifies that both the script execution and the output verification steps within the test file passed, demonstrating the effect of the OS negation check. ```text Running tests for os_specific_negation.md: ✓ running script 'os_specific_negation' succeeded ✓ verifying stdout from 'os_specific_negation' succeeded 2 functions run (2 succeeded / 0 failed) ``` -------------------------------- ### Verifying Directory Listing Output Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Verifies the output of the `ls` script, expecting it to list `test_file.txt`, confirming the script ran in the correct workspace directory. ```text test_file.txt ``` -------------------------------- ### Defining Specdown Test File (Markdown) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_exit_codes.md Defines the content of the `exit_example.md` file used for testing exit codes in Specdown. It includes two nested shell script blocks with specific expected exit codes. ```markdown # Example of testing exit codes The following will success: ```shell,script(name="command_1", expected_exit_code=25) exit 25 ``` But the next one will fail: ```shell,script(name="command_2", expected_exit_code=0) exit 1 ``` ``` -------------------------------- ### Verifying Shell Command Output with SpecDown Source: https://github.com/specdown/specdown/blob/master/README.md This block contains the expected standard output (`stdout`) from the shell script named 'hello-specdown'. SpecDown will compare the actual output of the script against the content of this block. ```text Hello SpecDown ``` -------------------------------- ### Run specdown with Unknown Function File - shell Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Executes the `specdown run` command on the `unknown_function_example.md` file, expecting an exit code of 1 due to the unknown function error detected during parsing. ```shell specdown run unknown_function_example.md ``` -------------------------------- ### Expected Specdown Test Output (Text) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_exit_codes.md The expected output from running the `specdown run exit_example.md` command. It shows that `command_1` succeeded (exit code 25 matched) and `command_2` failed (expected 0, got 1). ```text Running tests for exit_example.md: ✓ running script 'command_1' succeeded ✗ running script 'command_2' failed (expected exitcode 0, got 1) === stdout: === stderr: 2 functions run (1 succeeded / 1 failed) ``` -------------------------------- ### Run specdown with Invalid Argument Option File - shell Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Executes the `specdown run` command on the `invalid_token_option_example.md` file, expecting an exit code of 1 due to the invalid argument option error detected during parsing. ```shell specdown run invalid_token_option_example.md ``` -------------------------------- ### Define Empty Spec File - specdown Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Defines a simple markdown file (`empty_spec.md`) with minimal content, used to demonstrate command-line argument errors when running specdown. ```markdown # Nothing to see here ``` -------------------------------- ### Empty Specdown Markdown File Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md A minimal markdown file (`empty_spec.md`) containing only a title, used as a placeholder for testing command-line argument validation errors in `specdown run`. ```markdown # Nothing to see here ``` -------------------------------- ### Running OS Specific Negation Test File (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Executes the `specdown run os_specific_negation.md` command to run the test file demonstrating OS negation. The `expected_exit_code=0` attribute indicates that the command is expected to succeed. ```shell specdown run os_specific_negation.md ``` -------------------------------- ### Output of Running Multiple Specdown Files Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Shows the expected console output when running `specdown run` with multiple files. It displays the test results for each file separately. ```text Running tests for example-file1.md: ✓ running script 'command_1' succeeded 1 functions run (1 succeeded / 0 failed) Running tests for example-file2.md: ✓ running script 'command_2' succeeded 1 functions run (1 succeeded / 0 failed) ``` -------------------------------- ### Running specdown with invalid shell command (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Demonstrates running the `specdown run` command with an invalid shell command argument, expected to fail with exit code 2 due to a parsing error in the command string. ```shell specdown run --shell-command 'invalid " command' invalid_shell_command_example.md ``` -------------------------------- ### Running Specdown Help Script (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Executes the `specdown -h` command using a shell script block named "os_specific". This script is intended to be run by Specdown and its output verified conditionally based on the target OS. ```shell specdown -h ``` -------------------------------- ### Verification of non-existent shell command error message (Text) Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Shows the expected error output when running specdown with a non-existent shell command, indicating that the program was not found. ```text Running tests for missing_shell_example.md: ✗ Failed to run command: does-not-exist [] (Error: program not found) 0 functions run (0 succeeded / 0 failed) ``` -------------------------------- ### Verify Output for Empty Shell Command Error - text Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Shows the expected output from `specdown run` when an empty string is provided as the shell command via `--shell-command`, indicating that the command is empty. ```text ✗ Invalid shell command provided: (Error: Command is empty) ``` -------------------------------- ### Verifying OS Specific Test Run Output (Text) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Defines the expected standard output after successfully running the `os_specific.md` test file. This block verifies that both the script execution and the output verification steps within the test file passed. ```text Running tests for os_specific.md: ✓ running script 'os_specific' succeeded ✓ verifying stdout from 'os_specific' succeeded 2 functions run (2 succeeded / 0 failed) ``` -------------------------------- ### Load Zsh Completion Script Source: https://github.com/specdown/specdown/blob/master/docs/cli/completion.md This command sources the generated Zsh completion script directly into the current shell session. This provides tab completion for specdown commands. ```shell source <(specdown completion zsh) ``` -------------------------------- ### Verifying Specdown Help Output on Windows (Text) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Defines the expected standard output when running the "os_specific" script on a Windows operating system. This block uses the `verify` attribute with `target_os="windows"` to apply the check only on Windows. ```text A tool to test markdown files and drive development from documentation. Usage: specdown.exe [OPTIONS] Commands: completion Output completion for a shell of your choice run Runs a given Markdown Specification strip Outputs a version of the markdown with all specdown functions removed help Print this message or the help of the given subcommand(s) Options: --no-colour Disables coloured output -h, --help Print help -V, --version Print version ``` -------------------------------- ### Define Markdown File with Unknown Function - specdown Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Defines a markdown file (`unknown_function_example.md`) containing a shell code block annotated with an unknown `function()` specdown function, intended to demonstrate an error when specdown parses the file. ```markdown # Unknown Function Example ```shell,function() echo "This script is annotated with an unknown function" ``` ``` -------------------------------- ### Echoing UTF-8 Character with Shell Script Source: https://github.com/specdown/specdown/blob/master/docs/specs/creating_test_files.md A simple shell script that uses the `echo` command to print a UTF-8 character (checkmark). This snippet demonstrates specdown's support for handling UTF-8 encoding in scripts. ```shell echo "✓" ``` -------------------------------- ### Run Specdown with Invalid Argument Type File Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Shell command to execute the `specdown run` command on the `invalid_argument_value_example.md` file, expected to fail because the `script()` function annotation uses an integer for the `name` argument instead of a string. The `expected_exit_code=1` indicates an expected failure. ```shell specdown run invalid_argument_value_example.md ``` -------------------------------- ### Generate Elvish Completion Script Source: https://github.com/specdown/specdown/blob/master/docs/cli/completion.md This command generates the shell completion script for Elvish. The output is the script content which can be loaded into the Elvish shell. ```shell specdown completion elvish ``` -------------------------------- ### Load PowerShell Completion Script Source: https://github.com/specdown/specdown/blob/master/docs/cli/completion.md This command sources the generated PowerShell completion script directly into the current shell session, enabling tab completion for specdown in PowerShell. ```shell . <(specdown completion powershell) ``` -------------------------------- ### Verifying Specdown Help Output on macOS (Text) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Defines the expected standard output when running the "os_specific" script on a macOS operating system. This block uses the `verify` attribute with `target_os="macos"` to apply the check only on macOS. ```text A tool to test markdown files and drive development from documentation. Usage: specdown [OPTIONS] Commands: completion Output completion for a shell of your choice run Runs a given Markdown Specification strip Outputs a version of the markdown with all specdown functions removed help Print this message or the help of the given subcommand(s) Options: --no-colour Disables coloured output -h, --help Print help -V, --version Print version ``` -------------------------------- ### Display Workspace Message (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Displays the content of `message.txt` located in the specdown workspace directory. This snippet is part of a test demonstrating workspace initialization. ```shell cat "$SPECDOWN_WORKSPACE_DIR"/message.txt ``` -------------------------------- ### Executing Shell Command with SpecDown Source: https://github.com/specdown/specdown/blob/master/README.md This shell command is embedded in the markdown and marked with `script(name="hello-specdown")`. SpecDown will execute this command when processing the document. ```shell echo "Hello SpecDown" ``` -------------------------------- ### Specdown Error Output for Empty Shell Command Arg Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md The expected error message output when running `specdown run` with an empty string provided for the `--shell-command` option, indicating that the shell command cannot be empty. ```text ✗ Invalid shell command provided: (Error: Command is empty)\n ``` -------------------------------- ### Run specdown with Empty Shell Command - shell Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Executes the `specdown run` command with an empty string (`''`) provided for the `--shell-command` argument, demonstrating an invalid command-line argument value. ```shell specdown run --shell-command '' empty_shell_command_example.md ``` -------------------------------- ### Verifying Specdown Help Output on Linux (Text) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Defines the expected standard output when running the "os_specific" script on a Linux operating system. This block uses the `verify` attribute with `target_os="linux"` to apply the check only on Linux. ```text A tool to test markdown files and drive development from documentation. Usage: specdown [OPTIONS] Commands: completion Output completion for a shell of your choice run Runs a given Markdown Specification strip Outputs a version of the markdown with all specdown functions removed help Print this message or the help of the given subcommand(s) Options: --no-colour Disables coloured output -h, --help Print help -V, --version Print version ``` -------------------------------- ### Load Bash Completion Script Source: https://github.com/specdown/specdown/blob/master/docs/cli/completion.md This command sources the generated Bash completion script directly into the current shell session. This provides tab completion for specdown commands. ```shell source <(specdown completion bash) ``` -------------------------------- ### Stripping Specdown Syntax from a File (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/stripping_specs.md This command uses the `specdown strip` subcommand to process a specified markdown file (`strip_example.md`) and output a version with all specdown-specific syntax removed. The output is shown in the following markdown block in the source document. ```shell specdown strip strip_example.md ``` -------------------------------- ### Verifying Specdown Output for Any Expectation Source: https://github.com/specdown/specdown/blob/master/docs/specs/output_expectations.md Shows the expected output from running `specdown run output_expectation_any.md`. It indicates that the script `stdout_and_stderr` succeeded because the `expected_output=any` setting allows both stdout and stderr. ```text Running tests for output_expectation_any.md: ✓ running script 'stdout_and_stderr' succeeded 1 functions run (1 succeeded / 0 failed) ``` -------------------------------- ### Generate Fish Completion Script Source: https://github.com/specdown/specdown/blob/master/docs/cli/completion.md This command generates the shell completion script for Fish. The output is the script content which needs to be saved to a specific directory for Fish to load it. ```shell specdown completion fish ``` -------------------------------- ### Run Specdown with Empty Shell Command Arg Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md Shell command executing `specdown run` with the `--shell-command` option provided with an empty string (`''`), which is an invalid value and is expected to cause a command-line argument error. The `expected_exit_code=2` indicates an expected failure. ```shell specdown run --shell-command '' empty_shell_command_example.md ``` -------------------------------- ### Define Markdown File with Missing Argument - specdown Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Defines a markdown file (`missing_function_argument_example.md`) containing a shell code block annotated with the `file()` function but missing the required `path` argument, demonstrating a parsing error. ```markdown # Unknown Function Example ```shell,file() This file has no path! ``` ``` -------------------------------- ### Output of Running Spec with --workspace-dir Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Shows the expected console output when running the spec with `--workspace-dir`. It confirms that the `ls` and `cat` scripts executed successfully within the specified workspace directory. ```text Running tests for workspace_dir_example.md: ✓ running script 'ls' succeeded ✓ verifying stdout from 'ls' succeeded ✓ running script 'cat' succeeded ✓ verifying stdout from 'cat' succeeded 4 functions run (4 succeeded / 0 failed) ``` -------------------------------- ### Specdown Error Output for Conflicting Workspace Args Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md The expected error message output when running `specdown run` with both `--workspace-dir` and `--temporary-workspace-dir` options provided, indicating that these arguments are mutually exclusive. ```text ✗ --workspace-dir and --temporary-workspace-dir cannot be specified at the same time\n ``` -------------------------------- ### Execute Specdown with Missing Shell Executable (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/errors.md This command runs specdown against a markdown file, specifying a non-existent executable via `--shell-command`. It is expected to fail because the specified shell command cannot be found. ```shell specdown run --shell-command 'does-not-exist' missing_shell_example.md ``` -------------------------------- ### Verifying File Contents Output Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Verifies the output of the `cat` script, expecting it to display "file in workspace dir", confirming the script accessed the file in the correct workspace directory. ```text file in workspace dir ``` -------------------------------- ### Verify Output for Conflicting Workspace Args Error - text Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Shows the expected output from `specdown run` when conflicting workspace directory arguments (`--workspace-dir` and `--temporary-workspace-dir`) are provided, indicating that they cannot be used together. ```text ✗ --workspace-dir and --temporary-workspace-dir cannot be specified at the same time ``` -------------------------------- ### Read Message File in Working Directory (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md This shell script is defined within the `working_dir_example.md` spec file. It attempts to read `message.txt`. When the spec is run with `--working-dir working_dir`, this command will execute inside the `workspace/working_dir` directory. ```shell cat message.txt ``` -------------------------------- ### Run specdown with Invalid Argument Value File - shell Source: https://github.com/specdown/specdown/blob/master/docs/errors.md Executes the `specdown run` command on the `invalid_argument_value_example.md` file, expecting an exit code of 1 due to the invalid argument value type error detected during parsing. ```shell specdown run invalid_argument_value_example.md ``` -------------------------------- ### Generate Bash Completion Script Source: https://github.com/specdown/specdown/blob/master/docs/cli/completion.md This command generates the shell completion script for Bash. The output is the script content which can then be sourced or saved to a file. ```shell specdown completion bash ``` -------------------------------- ### Running Specdown Test with Any Output Expectation Source: https://github.com/specdown/specdown/blob/master/docs/specs/output_expectations.md Executes the specdown test defined in `output_expectation_any.md`. This command runs the embedded shell script and checks if its output matches the `expected_output=any` configuration. ```shell specdown run output_expectation_any.md ``` -------------------------------- ### Output of Running Spec with --temporary-workspace-directory Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md Shows the expected console output when running the spec with `--temporary-workspace-directory`. It confirms that the `ls` script (checking for the non-existent file) succeeded, as it ran in the temporary directory where the file was not present. ```text Running tests for temporary_workspace_dir_example.md: ✓ running script 'ls' succeeded 1 functions run (1 succeeded / 0 failed) ``` -------------------------------- ### Verify Default Shell is Bash (Text) Source: https://github.com/specdown/specdown/blob/master/docs/cli/running_specs.md This text block is defined within the `setting_the_shell_example.md` spec file. It verifies that the output of the `get_shell_name` script is `bash`, which is the default shell used by specdown. ```text bash ``` -------------------------------- ### Running OS Specific Test File (Shell) Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Executes the `specdown run os_specific.md` command to run the test file containing OS-specific checks. The `expected_exit_code=0` attribute indicates that the command is expected to succeed. ```shell specdown run os_specific.md ``` -------------------------------- ### Specdown Error Output for Verifying Unknown Script Source: https://github.com/specdown/specdown/blob/master/docs/errors_windows.md The expected error message output when running `specdown` on a spec file that attempts to verify a script name that has not been previously defined or executed. It clearly states that no script with that name was found. ```text Running tests for verify_unknown_script_example.md:\n\n ✗ Failed to verify the output of 'unknown': No script with that name has been executed yet.\n\n 0 functions run (0 succeeded / 0 failed).\n ``` -------------------------------- ### Defining Markdown File with Any Output Expectation Source: https://github.com/specdown/specdown/blob/master/docs/specs/output_expectations.md Defines a markdown file named `output_expectation_any.md` containing a shell script that outputs to both stdout and stderr, configured with `expected_output=any`. This tests the default behavior where any output is acceptable. ```markdown # Any Example Run a script which outputs some stdout and stderr. ```shell,script(name="stdout_and_stderr", expected_output=any) echo "Good stdout" echo "Good stderr" 1>&2 ``` ``` -------------------------------- ### Defining Script with Stdout/Stderr Shell Source: https://github.com/specdown/specdown/blob/master/docs/specs/verifying_script_output.md Defines a shell script named "stdout_and_stderr" that outputs text to both standard output and standard error streams. This script is embedded within a Specdown markdown file (`verify_example.md`) to serve as the target for subsequent verification steps. ```shell echo "Good stdout" echo "Bad stderr" 1>&2 ```