Document testing blocks

.gitignore

@@ -33,6 +33,3 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
-
-# testing files
-test*

docs/0.6.0-alpha/getting_started/testing.md

@@ -0,0 +1,44 @@
+
+Test blocks are dedicated scopes for writing tests. They are executed only when running the `amber test` command and are ignored during normal compilation. Test blocks can be optionally named using a string literal. This improves readability and allows for targetted execution.
+
+## Syntax
+```ab
+import { assert } from "std/test"
+
+// Unique named test block
+test "can multiply numbers" {
+    let result = 10 * 2
+    assert(result == 20)
+}
+
+// Unnamed test block (only one allowed per file)
+test {
+    let name = "Amber"
+    assert(name + " Lang" == "Amber Lang")
+}
+```
+
+# CLI Test Filtering
+
+The `amber test` command is designed to verify the correctness of your code by executing test blocks. By default, it recursively finds and runs all tests in the current directory. You can narrow down which tests to run by providing filter arguments.
+
+## Filtering Tests
+
+You can run a specific subset of tests by providing a filter argument. This argument performs a substring match against both the **filename** and the **test name**.
+
+```bash
+# Run all tests located in the current directory containing "variable" in their name or filename
+amber test . "variable"
+```
+
+## Targeting Specific Files
+
+Instead of running tests from the current directory, you can specify a particular file or directory to scan.
+
+```bash
+# Run all tests inside main.ab
+amber test main.ab
+
+# Run all tests in main.ab that contain "zip" in their name
+amber test main.ab "zip"
+```

docs/0.6.0-alpha/getting_started/usage.md

@@ -4,7 +4,7 @@ The Amber CLI can be used as a runtime or as a compiler.
 
 The Amber CLI syntax uses subcommands, like the Git CLI:
 
-*This output is generated from the 0.5.1-alpha version.*
+*This output is generated from the 0.5.2-alpha version.*
 ```
 Usage: amber [OPTIONS] [INPUT] [ARGS]... [COMMAND]
 
@@ -15,6 +15,7 @@ Commands:
   build       Compile Amber script to Bash
   docs        Generate Amber script documentation
   completion  Generate Bash completion script
+  test        Run Amber tests
   help        Print this message or the help of the given subcommand(s)
 
 Arguments:
@@ -97,6 +98,16 @@ Furthermore, Amber adds a _shebang_ at the top of the compiled script. This enab
 $ ./output.sh
 ```
 
+## Testing
+
+Amber comes with a built-in test runner. You can define named test blocks in your code and execute them using the `amber test` command.
+
+```sh
+$ amber test
+```
+
+For more details on writing and filtering tests, please refer to the [Testing guide](https://docs.amber-lang.com/getting_started/testing).
+
 ## Syntax Highlighting
 
 [VS Code](https://code.visualstudio.com) as well as [Zed](https://zed.dev) now have built-in LSP integration.

docs/0.6.0-alpha/index.json

@@ -12,6 +12,10 @@
                     "path": "getting_started/usage",
                     "title": "Usage"
                 },
+                {
+                    "path": "getting_started/testing",
+                    "title": "Testing"
+                },
                 {
                     "path": "getting_started/whats_new",
                     "title": "What's new"
@@ -120,6 +124,11 @@
                     "title": "Math",
                     "disableLevels": [3]
                 },
+                {
+                    "path": "stdlib/doc/test",
+                    "title": "Test",
+                    "disableLevels": [3]
+                },
                 {
                     "path": "stdlib/doc/text",
                     "title": "Text",

docs/0.6.0-alpha/stdlib/doc/test.md

@@ -0,0 +1,31 @@
+## `assert`
+
+```ab
+pub fun assert(condition: Bool) 
+```
+
+Asserts that a boolean condition is true. Fails the test with exit code `1` if false.
+### Usage
+```ab
+import { assert } from "std/test"
+
+let user_age = 18
+assert(user_age >= 18)
+```
+
+## `assert_eq`
+
+```ab
+pub fun assert_eq(left, right) 
+```
+
+Asserts that two values are equal. Fails the test with exit code `1` if they are not equal.
+### Usage
+```ab
+import { assert_eq } from "std/test"
+
+let expected = [1, 2, 3]
+let actual = [1, 2, 3]
+assert_eq(expected, actual)
+```
+

src/components/Markdown/amber-config.json

@@ -35,6 +35,7 @@
         "succeeded",
         "sudo",
         "exited",
+        "test",
         "then",
         "trust",
         "unsafe",