refactor: convert tests to user stories, so they're executable docume…

…ntation

.github/workflows/ci.yaml

@@ -11,15 +11,15 @@ jobs:
                 scaffold-version:
                     - v0.3.0
                 preset:
-                    - kitchen-sink
-                    - shell
+                    - cpp
+                    - go
                     - java
                     - js
-                    - go
+                    - kitchen-sink
+                    - minimal
                     - py
-                    - cpp
                     - rust
-                    - minimal
+                    - shell
         runs-on: ubuntu-latest
         steps:
             - uses: actions/checkout@v4
@@ -59,33 +59,9 @@ jobs:
               working-directory: "${{ steps.scaffold.outputs.dir }}"
               run: git diff --exit-code
 
-            - name: Tools smoke test
-              working-directory: "${{ steps.scaffold.outputs.dir }}"
-              if: "${{ matrix.preset == 'kitchen-sink' }}"
-              run: |
-                ./tools/copier --help
-                ./tools/yq --help
-              
-            - name: Java smoke test
+            - name: User Stories
               working-directory: "${{ steps.scaffold.outputs.dir }}"
-              if: "${{ matrix.preset == 'java' }}"
-              run: |
-                mkdir src
-                >src/Demo.java echo -e 'class Demo { public static void main(String[] args) { System.out.println("Hello from Java");}}'
-                >src/BUILD.bazel echo -e 'java_binary(name="Demo", srcs=["Demo.java"])'
-                output="$(bazel run src:Demo)"
-                [[ "${output}" == "Hello from Java" ]] || { echo >&2 "Wanted output 'Hello from Java' but got '${output}'" ; exit 1 ; }
-
-            - name: Python smoke test
-              working-directory: "${{ steps.scaffold.outputs.dir }}"
-              if: "${{ matrix.preset == 'py' }}"
-              run: |
-                mkdir app
-                >app/__main__.py echo -e 'import requests\nprint(requests.get("https://api.github.com").text)'
-                >app/app_test.py echo -e 'def test_bad():\n  assert 1 == 2'
-                sed -i 's/dependencies = \[/dependencies = ["requests",/' pyproject.toml
-                ./tools/repin
-                bazel run //app:app_bin
+              run: $GITHUB_WORKSPACE/user_stories/${{ matrix.preset}}
 
             - name: Python test that fails
               continue-on-error: true # for some reason `bazel test || true` still failing.
@@ -98,48 +74,6 @@ jobs:
               if: "${{ matrix.preset == 'py' }}"
               run: grep "FAILED app/app_test.py::test_bad - assert 1 == 2" $(bazel info bazel-testlogs)/app/app_test/test.log
 
-            - name: Go smoke test
-              working-directory: "${{ steps.scaffold.outputs.dir }}"
-              if: "${{ matrix.preset == 'go' }}"
-              run: ./tools/go mod tidy
-
-            - name: JS smoke test
-              working-directory: "${{ steps.scaffold.outputs.dir }}"
-              if: "${{ matrix.preset == 'js' }}"
-              run: ./tools/pnpm list
-
-            - name: Shell smoke test
-              working-directory: "${{ steps.scaffold.outputs.dir }}"
-              if: "${{ matrix.preset == 'shell' }}"
-              run: |
-                >hello.sh echo -e '#!/usr/bin/env bash\necho "Hello from Bash"'
-                chmod u+x hello.sh
-                bazel configure || true
-                output="$(bazel run :hello)"
-                [[ "${output}" == "Hello from Bash" ]] || { echo >&2 "Wanted output 'Hello from Bash' but got '${output}'" ; exit 1 ; }
-
-            - name: Rust smoke test
-              working-directory: "${{ steps.scaffold.outputs.dir }}"
-              if: "${{ matrix.preset == 'rust' }}"
-              run: |
-                mkdir -p hello_world/src
-
-                cat >hello_world/BUILD.bazel <<EOF
-                load("@rules_rust//rust:defs.bzl", "rust_binary")
-
-                rust_binary(
-                    name = "hello_world",
-                    srcs = ["src/main.rs"],
-                )
-                EOF
-
-                cat >hello_world/src/main.rs <<EOF
-                fn main() { println!("Hello from Rust"); }
-                EOF
-
-                output="$(bazel run //hello_world)"
-                [[ "${output}" == "Hello from Rust" ]] || { echo >&2 "Wanted output 'Hello from Rust' but got '${output}'" ; exit 1 ; }
-
             - run: bazel lint ...
               working-directory: "${{ steps.scaffold.outputs.dir }}"
 

user_stories/cpp

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Example user workflows within an `aspect init`-generated repository
+# where the C++ language is used.
+set -o errexit -o pipefail -o nounset
+
+# TODO(alex): create a cc_binary and run it

user_stories/go

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Example user workflows within an `aspect init`-generated repository
+# with the Go language enabled.
+set -o errexit -o pipefail -o nounset
+
+# Create/update the go.mod file
+./tools/go mod tidy
+

user_stories/java

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Example user workflows within an `aspect init`-generated repository
+# with the Java language enabled.
+
+mkdir src
+>src/Demo.java cat <<EOF
+class Demo {
+    public static void main(String[] args) {
+        System.out.println("Hello from Java");
+    }
+}
+EOF
+
+# We didn't wire up the BUILD file generator for Java yet, so users
+# are forced to write this manually.
+>src/BUILD.bazel cat <<EOF
+java_binary(name="Demo", srcs=["Demo.java"])
+EOF
+
+# Now the application should run
+output="$(bazel run src:Demo)"
+
+# Verify it produced the expected output
+[[ "${output}" == "Hello from Java" ]] || {
+    echo >&2 "Wanted output 'Hello from Java' but got '${output}'"
+    exit 1
+}

user_stories/js

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Example user workflows within an `aspect init`-generated repository
+# with the JavaScript / TypeScript language enabled.
+set -o errexit -o pipefail -o nounset
+
+# Demonstrate that the pnpm tool can be run
+./tools/pnpm list

user_stories/kitchen-sink

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Example user workflows within an `aspect init`-generated repository
+# that work across all languages.
+
+./tools/copier --help
+./tools/yq --help

user_stories/minimal

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Verify that the templated Bazel repository works with no languages selected.
+set -o errexit -o pipefail -o nounset
+
+bazel build ...

user_stories/py

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Verify that the templated Bazel repository works with the 'shell' preset.
+set -o errexit -o pipefail -o nounset
+
+mkdir app
+# Create a simple application with an external package dependency
+>app/__main__.py cat <<EOF
+import requests
+print(requests.get("https://api.github.com").status_code)
+EOF
+
+# Create a simple failing test
+>app/app_test.py cat <<EOF
+def test_bad():
+  assert 1 == 2
+EOF
+
+# Declare our dependency in the project definition
+# NB: there's not a good machine-editing utility for TOML
+sed -i 's/dependencies = \[/dependencies = ["requests",/' pyproject.toml
+
+# Run the re-pinning operation
+./tools/repin
+
+# Now the application executes
+output=$(bazel run //app:app_bin)
+
+# Verify the application output matches expectation
+[[ "${output}" == "200" ]] || {
+    echo >&2 "Wanted output '200' but got '${output}'"
+    exit 1
+}

user_stories/rust

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Verify that the templated Bazel repository works with the 'shell' preset.
+set -o errexit -o pipefail -o nounset
+
+mkdir -p hello_world/src
+
+# Create a tiny Rust program
+cat >hello_world/src/main.rs <<EOF
+fn main() { println!("Hello from Rust"); }
+EOF
+
+# We don't have any BUILD file generation for Rust yet,
+# so users are forced to create it manually.
+cat >hello_world/BUILD.bazel <<EOF
+load("@rules_rust//rust:defs.bzl", "rust_binary")
+
+rust_binary(
+    name = "hello_world",
+    srcs = ["src/main.rs"],
+)
+EOF
+
+# Run the program and assert that it produces the expected output
+output="$(bazel run //hello_world)"
+[[ "${output}" == "Hello from Rust" ]] || {
+    echo >&2 "Wanted output 'Hello from Rust' but got '${output}'"
+    exit 1
+}

user_stories/shell

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Verify that the templated Bazel repository works with the 'shell' preset.
+set -o errexit -o pipefail -o nounset
+
+# Write a simple Bash executable
+>hello.sh echo -e '#!/usr/bin/env bash\necho "Hello from Bash"'
+chmod u+x hello.sh
+
+# Generate BUILD files, see .aspect/cli/shell.star for the logic used
+bazel configure || true
+
+# Verify that running the Bash program produces the expected output
+output="$(bazel run :hello)"
+[[ "${output}" == "Hello from Bash" ]] || {
+    echo >&2 "Wanted output 'Hello from Bash' but got '${output}'"
+    exit 1
+}