recipe-maintainer/.claude/commands/recipe-test-new.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Test a recipe's first-time initialization from scratch	<recipe-name>	Bash Read Write Glob Grep WebFetch

Recipe Test New

Test that a recipe works correctly for first-time initialization: remove the existing test instance entirely, recreate it from scratch, deploy, run post-deploy steps, and verify everything works.

Important: All abra commands that read the recipe (deploy, ps, cmd) MUST use --chaos so they use the current local recipe checkout, including any uncommitted changes.

TTY workaround: Several abra subcommands fail with "the input device is not a TTY" in non-interactive environments. Wrap these with script -qefc "..." /dev/null to provide a pseudo-TTY.

The recipe name is: $ARGUMENTS

Read and follow the instructions in .claude/commands/includes/logging.md. Read and follow the instructions in .claude/commands/includes/guidelines.md.

Steps

1. Free server resources by running /test-context-reset $ARGUMENTS to undeploy unrelated apps from the test server while keeping this recipe's dependencies running.

2. Get the domain and server for this recipe:

   python3 scripts/get_test_instance.py --recipe $ARGUMENTS
   

   This outputs DOMAIN and SERVER for the active instance.

   • If the recipe has no recipe-info/$ARGUMENTS/recipe.toml, tell the user to run /recipe-init $ARGUMENTS first and stop.

3. Read the test plan from recipe-info/$ARGUMENTS/test.md.

   • Note the post-deploy steps — these will need to be run after redeploying.
   • Note any prerequisites (e.g. Keycloak must be running).
   • Note which automated check scripts are referenced.

4. Read the recipe at ~/.abra/recipes/$ARGUMENTS/compose.yml and ~/.abra/recipes/$ARGUMENTS/abra.sh to understand the services and available commands.

5. Undeploy the existing instance:

   • Run: abra app undeploy <DOMAIN> --no-input
   • If the app is not deployed, note that and continue.

6. Remove the app entirely (secrets, volumes, env file):

   • Run: abra app rm <DOMAIN> --force --no-input
   • This deletes all secrets, volumes, and the local env file.
   • If it fails because the app doesn't exist, that's fine — continue.

7. Recreate the app instance:

   • Run:

     abra app new $ARGUMENTS --server <SERVER> --domain <DOMAIN> --secrets --no-input
     

   • --secrets auto-generates secrets.
   • Save the generated secrets to recipe-info/$ARGUMENTS/secrets.json:

     abra app secret generate <DOMAIN> --all --machine > recipe-info/$ARGUMENTS/secrets.json
     

   • Check the recipe's README (~/.abra/recipes/$ARGUMENTS/README.md) and test.md for any env vars that need to be configured before deploying. If there are any, set them in the app's env file at ~/.abra/servers/<SERVER>/<DOMAIN>.env.
   • If the recipe has secrets that must be manually inserted (not auto-generated), check recipe-info/$ARGUMENTS/test.md for instructions and apply them.

8. Deploy from scratch:

   • Run: abra app deploy <DOMAIN> --chaos --force --no-input
   • Wait for services to come up. Check with abra app ps <DOMAIN> --chaos --no-input -m.
   • Allow up to 90 seconds for all services to converge. If abra reports a deploy timeout but app ps shows services running, treat it as success.

9. Run post-deploy steps as documented in recipe-info/$ARGUMENTS/test.md under "Post-Deploy Steps":

   • Typically includes things like database migrations, bucket creation, SSO integration setup scripts, etc.
   • Run each step and confirm it succeeds.
   • If a step involves running a setup script (e.g. setup_keycloak_integration.py), check if it exists in recipe-info/$ARGUMENTS/ and run it.
   • If post-deploy steps require a redeploy, do so: abra app deploy <DOMAIN> --chaos --force --no-input

10. Run the test suite:

    • Discover and run all test scripts from recipe-info/$ARGUMENTS/tests/*.py.
    • For each script, record PASS (exit 0) or FAIL (non-zero).
    • Read recipe-info/$ARGUMENTS/test.md and perform URL-based checks using curl or WebFetch.
    • If no tests exist at all, at minimum curl https://<DOMAIN> and check for HTTP 200.

11. Summarise results:

    Report each phase:

    Phase	Result
    Undeploy + remove	PASS / FAIL
    Recreate instance	PASS / FAIL
    Fresh deploy	PASS / FAIL
    Post-deploy steps	PASS / FAIL (detail per step)
    Test suite	PASS / FAIL (detail per test)

    • If all phases passed: confirm the recipe's first-time initialization works correctly.
    • If any phase failed: highlight which step failed, show relevant error output, and suggest troubleshooting.