@@ -4,21 +4,108 @@ title: Hooks & Actions
 sidebar_label: Hooks & Actions
 ---
 
-To make a functional tutorial, tutorial creators need a bit more control over what can be run and when. For example, a test runner wouldn't really work if the package dependencies for that test runner weren't installed.
+To make a functional tutorial, tutorial creators need a bit more control over what can be run and when.
 
-An action is a piece of functionality that can be run. These include:
-
-- `commands` - a list of cli commands to run. For example, "npm install"
-- `vscodeCommands` - a list of vscode API commands to run. For example, "setLayout" to change the layout of windows
-- `watchers` - a list of files to listen to. If a file changes, the test runner will run automatically
-- `files` - a list of files to open in the users workspace to drive the users attention.
-- `subtasks` - a task made up of multiple other tests where all must pass to continue
-- `filter` - a regex passed into the test runner to limit the tests returned
+## Hooks
 
-A hook in CodeRoad is a place where a tutorial creator can tap in to run an action. Hooks include:
+A hook in CodeRoad is a place where a tutorial can tap in to run an action. Hooks include:
 
 - `config.setup` - when the tutorial setup. This is a great place to setup your test runner.
-- `task.setup` - when a task is started
-- `task.solution` - when a solution is loaded from a reset
+- `step.setup` - when a task is started
+- `step.solution` - when a solution is loaded from a reset
 
 Hooks and actions combine to provide a flexible environment for tutorial development.
+
+To see which hooks run where, consult [the hooks list in the codebase](https://github.com/coderoad/coderoad-vscode/blob/master/src/services/hooks/index.ts).
+
+## Actions
+
+An action is a piece of functionality that can be run. These include:
+
+### `commands` (string[])
+
+A list of cli commands to run. For example, "npm install"
+
+```yaml
+setup:
+  commands:
+    - 'npm install'
+```
+
+In the example above, `npm install` will run in the root of the workspace.
+
+### `vscodeCommands` (string[] | [command: string, params: any][])
+
+A list of vscode API commands to run. Commands may be a single string, or an array with the command, and params.
+
+```yaml
+setup:
+  vscodeCommands:
+    - 'workbench.action.terminal.toggleTerminal' # toggle terminal
+    - [
+        'setEditorLayout',
+        { orientation: 0, groups: [{ groups: [{}, {}], size: 0.5 }, { groups: [{}, {}], size: 0.5 }] },
+      ] # set the orientation of windows and sizes
+```
+
+For example, "toggleTerminal" toggles the terminal, while "setLayout" changes the layout of windows.
+
+There are a number of options in the VSCode API. More info at:
+
+- [vscode commands API](https://code.visualstudio.com/api/references/vscode-api#commands)
+- [commands with params](https://code.visualstudio.com/api/references/commands)
+- [commands without params](https://code.visualstudio.com/docs/getstarted/keybindings)
+
+### `watchers` (string[])
+
+A list of files globs to listen to. If a file changes that matches the pattern, the test runner will run automatically.
+
+```yaml
+setup:
+  watchers:
+    - 'package.json'
+    - 'node_modules/express'
+```
+
+The example above will run tests if the `package.json` file changes, or if there is a change in `node_modules/express`. This is a good way to run tests if a package is installed.
+
+Note that watchers are throttled to run no more than once per second.
+
+Read more about [glob patterns](https://code.visualstudio.com/api/references/vscode-api#GlobPattern).
+
+### `files` (string[])
+
+A list of files to open in the users workspace to drive the users attention.
+
+```yaml
+setup:
+  files:
+    - 'README.md'
+```
+
+The above example will open the "README.md" file in the users workspace. Note that file paths are relative to the workspace root.
+
+### `filter` (string)
+
+A regex passed into the test runner to limit the tests returned
+
+```yaml
+setup:
+  filter: 'level_1_tests'
+```
+
+Will restrict tests to only run a subset of tests that match the filter. Filter depends on your test runner, and can be configured in the test runner.
+
+```yaml
+config:
+  testRunner:
+    command: ./node_modules/.bin/mocha
+    args:
+      filter": --grep
+```
+
+Essentially, the above example will run `./node_modules/.bin/mocha --grep level_1_tests` as the test command.
+
+### `subtasks` (boolean)
+
+A task made up of multiple other tests where all must pass to continue
@@ -9,17 +9,20 @@ import { onError as telemetryOnError } from '../telemetry'
 import { runTest } from '../../actions/onTest'
 import logger from '../logger'
 
+// run at the end of when a tutorial is configured
 export const onInit = async (actions: TT.StepActions): Promise<void> => {
   await loadCommits(actions?.commits)
   await runCommands(actions?.commands)
   await runVSCodeCommands(actions?.vscodeCommands)
 }
 
+// run when a level starts
 export const onLevelEnter = async (actions: TT.StepActions): Promise<void> => {
   await loadCommits(actions?.commits)
   await runCommands(actions?.commands)
 }
 
+// run when a step starts
 export const onSetupEnter = async (actions: TT.StepActions): Promise<void> => {
   await loadCommits(actions?.commits)
   await openFiles(actions?.files)
@@ -28,6 +31,7 @@ export const onSetupEnter = async (actions: TT.StepActions): Promise<void> => {
   await runVSCodeCommands(actions?.vscodeCommands)
 }
 
+// run when a step solution starts
 export const onSolutionEnter = async (actions: TT.StepActions): Promise<void> => {
   await git.clear()
   await loadCommits(actions?.commits)
@@ -37,25 +41,30 @@ export const onSolutionEnter = async (actions: TT.StepActions): Promise<void> =>
   await runTest()
 }
 
+// run when "reset" is triggered
 export const onReset = async (actions: TT.StepActions): Promise<void> => {
   await resetWatchers()
   await runCommands(actions?.commands)
   await runVSCodeCommands(actions?.vscodeCommands)
 }
 
+// run when an uncaught exception is thrown
 export const onError = async (error: Error): Promise<void> => {
   telemetryOnError(error)
 }
 
+// run when a step task passes
 export const onStepComplete = async ({ levelId, stepId }: { levelId: string; stepId: string }): Promise<void> => {
   git.saveCommit(`Save progress: ${stepId}`)
   logger(`ON STEP COMPLETE: ${JSON.stringify({ levelId, stepId })}`)
 }
 
+// run when a level is complete (all tasks pass or no tasks)
 export const onLevelComplete = async ({ levelId }: { levelId: string }): Promise<void> => {
   logger(`ON LEVEL COMPLETE: ${JSON.stringify(levelId)}`)
 }
 
+// run when all levels are complete
 export const onTutorialComplete = async ({ tutorialId }: { tutorialId: string }): Promise<void> => {
   logger(`ON TUTORIAL COMPLETE: ${JSON.stringify(tutorialId)}`)
 }
Original file line number	Diff line number	Diff line change
`@@ -9,17 +9,20 @@ import { onError as telemetryOnError } from '../telemetry'`
`9`	`9`	`import { runTest } from '../../actions/onTest'`
`10`	`10`	`import logger from '../logger'`
`11`	`11`
	`12`	`+// run at the end of when a tutorial is configured`
`12`	`13`	`export const onInit = async (actions: TT.StepActions): Promise<void> => {`
`13`	`14`	`await loadCommits(actions?.commits)`
`14`	`15`	`await runCommands(actions?.commands)`
`15`	`16`	`await runVSCodeCommands(actions?.vscodeCommands)`
`16`	`17`	`}`
`17`	`18`
	`19`	`+// run when a level starts`
`18`	`20`	`export const onLevelEnter = async (actions: TT.StepActions): Promise<void> => {`
`19`	`21`	`await loadCommits(actions?.commits)`
`20`	`22`	`await runCommands(actions?.commands)`
`21`	`23`	`}`
`22`	`24`
	`25`	`+// run when a step starts`
`23`	`26`	`export const onSetupEnter = async (actions: TT.StepActions): Promise<void> => {`
`24`	`27`	`await loadCommits(actions?.commits)`
`25`	`28`	`await openFiles(actions?.files)`
`@@ -28,6 +31,7 @@ export const onSetupEnter = async (actions: TT.StepActions): Promise<void> => {`
`28`	`31`	`await runVSCodeCommands(actions?.vscodeCommands)`
`29`	`32`	`}`
`30`	`33`
	`34`	`+// run when a step solution starts`
`31`	`35`	`export const onSolutionEnter = async (actions: TT.StepActions): Promise<void> => {`
`32`	`36`	`await git.clear()`
`33`	`37`	`await loadCommits(actions?.commits)`
`@@ -37,25 +41,30 @@ export const onSolutionEnter = async (actions: TT.StepActions): Promise<void> =>`
`37`	`41`	`await runTest()`
`38`	`42`	`}`
`39`	`43`
	`44`	`+// run when "reset" is triggered`
`40`	`45`	`export const onReset = async (actions: TT.StepActions): Promise<void> => {`
`41`	`46`	`await resetWatchers()`
`42`	`47`	`await runCommands(actions?.commands)`
`43`	`48`	`await runVSCodeCommands(actions?.vscodeCommands)`
`44`	`49`	`}`
`45`	`50`
	`51`	`+// run when an uncaught exception is thrown`
`46`	`52`	`export const onError = async (error: Error): Promise<void> => {`
`47`	`53`	`telemetryOnError(error)`
`48`	`54`	`}`
`49`	`55`
	`56`	`+// run when a step task passes`
`50`	`57`	`export const onStepComplete = async ({ levelId, stepId }: { levelId: string; stepId: string }): Promise<void> => {`
`51`	`58`	git.saveCommit(`Save progress: ${stepId}`)
`52`	`59`	logger(`ON STEP COMPLETE: ${JSON.stringify({ levelId, stepId })}`)
`53`	`60`	`}`
`54`	`61`
	`62`	`+// run when a level is complete (all tasks pass or no tasks)`
`55`	`63`	`export const onLevelComplete = async ({ levelId }: { levelId: string }): Promise<void> => {`
`56`	`64`	logger(`ON LEVEL COMPLETE: ${JSON.stringify(levelId)}`)
`57`	`65`	`}`
`58`	`66`
	`67`	`+// run when all levels are complete`
`59`	`68`	`export const onTutorialComplete = async ({ tutorialId }: { tutorialId: string }): Promise<void> => {`
`60`	`69`	logger(`ON TUTORIAL COMPLETE: ${JSON.stringify(tutorialId)}`)
`61`	`70`	`}`