Debugger Actions

• assert(condition: boolean, message?: string): void

  Verifies that the given condition is true. If it is not, then an error is thrown with the given message. This function is useful for automated testing since tests should ideally throw an error if the test fails. It can also be useful to make sure that some important code is only run if a precondition is met.

  The first parameter is a boolean and is the condition that should be verified.

  The second parameter is optional and is a string and is the message that should be included in the error.

  Examples

  Assert that the tag color is "blue"

  assert(tags.color === "blue", "The tag color is not blue!");

• assertEqual(first: any, second: any): void

  Verifies that the given values are equal to each other. If they are not, then an error is thrown. This function is useful for automated testing since tests should ideally throw an error if the test fails. It can also be useful to make sure that some important code is only run if a precondition is met.

  The first parameter is a any and is the first value to test.

  The second parameter is a any and is the second value to test.

  Examples

  Assert that the tag color is "blue"

  assertEqual(tags.color, "blue");

  Assert that the bot contains some specific tag values

  assertEqual(tags, {
      color: "blue",
      home: true,
      homeX: 0,
      homeY: 0
  });

• os.attachDebugger(debug: Debugger, options?: AttachDebuggerOptions): Promise<void>

  Attaches the given debugger to the CasualOS frontend. This causes the given debugger to be treated like another inst that has been loaded simultaneously with the current inst. This feature makes it useful for inspecting the bots in a debugger or even for setting up a sandbox that you control.

  Note that because debuggers are entirely separate environments, the debugger gets its own configBot and portal bots. This means that in order for bots to show up in the portals, you need to set the corresponding portal on the debugger's configBot. For portals that are stored in the URL (like the gridPortal), this is done automatically. But for other portals (like the miniGridPortal or the wrist portals), you need to manage this manually.

  Returns a promise that resolves when the debugger has been attached.

  The first parameter is a Debugger and is the debugger that you want to be attached to the runtime.

  The second parameter is optional and is a AttachDebuggerOptions and is the options that should be used to attach the debugger.

  Examples

  Create and attach a debugger

  const debug = await os.createDebugger();
  
  // Create a bot in the debugger.
  debug.create({
      home: true
      label: 'Test'
  });
  
  // Attach the debugger to CasualOS.
  await os.attachDebugger(debug);

  Attach a debugger with a tag mapper that renames "home" tags to "testHome"

  const debug = await os.createDebugger();
  
  // Create a bot in the debugger.
  debug.create({
      home: true
      label: 'Test'
  });
  
  // Attach the debugger to CasualOS.
  // Because we're providing a tag mapper, the frontend won't see the "home" tag in debugger bots,
  // instead it will see "testHome" tags.
  await os.attachDebugger(debug, {
      tagNameMapper: {
          forward: (tag) => {
              if (tag.startsWith('home')) {
                  return `testHome${tag.slice('home'.length)}`;
              }
  
              return tag;
          },
          reverse: (tag) => {
              if (tag.startsWith('testHome')) {
                  return tag.slice('testHome'.length);
              }
  
              return tag;
          }
      }
  });

• os.createDebugger(options?: NormalDebuggerOptions): Promise<Debugger>

  Creates a debug environment that can be used to simulate bots in isolation from the rest of the inst. Returns a promise that resolves with an object that contains all of the action functions.

  One of the special things about debug environments is that the bots in the environment are totally isolated from regular bots. This means that functions like getBots(...filters) can only access bots that have been created in the debugger and actions like os.toast(message, duration) don't do anything automatically. This can be useful for automated testing where you want to see what some bots will do without actually letting them do anything.

  Additionally, debuggers can be configured to be pausable (see os.createDebugger(options)). This allows you to set pause triggers (also known as breakpoints) that temporarily stop the debugger at a specific location in a listener and allows you to inspect the current state of the script. Pausable debuggers work like normal debuggers, except that some specific functions return promises instead of a result. This is because those functions can trigger user code that could trigger a pause. When this is possible, the debugger returns a promise to your host code so you can properly handle the pause. (See the examples below for more information)

  The returned object can be used to create/find bots in the debug environment and simulate interactions. The debug environment also contains several functions that make it easy to observe what has happened inside the environment and therefore determine if everything was performed correctly.

  The first parameter is optional and is a NormalDebuggerOptions and is the options that should be used to configure the debugger.

  Examples

  Create a normal debugger and copy this bot into it.

  // Note: variables cannot be named "debugger" so we use the name "debug" instead.
  const debug = await os.createDebugger();
  const debuggerBot = debug.create(thisBot);

  Test a script in the debugger

  const debug = await os.createDebugger();
  const debuggerBot = debug.create({
      test: '@tags.hit = true;'
  });
  debug.shout('test');
  
  if (debuggerBot.tags.hit) {
      os.toast('Success!');
  } else {
      os.toast('Failed!');
  }

  Find out what actions a script performs

  const debug = await os.createDebugger();
  const debuggerBot = debug.create({
      test: '@os.toast("hello!")'
  });
  debug.shout('test');
  
  const actions = debug.getCommonActions();
  os.toast(actions);

  Create a debugger with a custom configBot

  const debug = await os.createDebugger({
      configBot: {
          test: '@console.log("Hello, World!");'
      }
  });
  debug.shout('test');

  Mask the web.get() function.

  const debug = await os.createDebugger();
  let url = "https://upload.wikimedia.org/wikipedia/commons/thumb/9/90/The_star_formation_region_Messier_17.jpg/1200px-The_star_formation_region_Messier_17.jpg";
  const debuggerBot = debug.create({
      url,
      test: '@return await web.get(tags.url)'
  });
  
  debug.web.get.mask(url)
      .returns({
          data: 'test data',
          status: 200
      });
  
  const [result] = debug.shout('test');
  
  assertEqual(result, {
      data: 'test data',
      status: 200
  });
  os.toast("Success!");

• os.createDebugger(options: PausableDebuggerOptions): Promise<PausableDebugger>

  Creates a pausable debug environment that can be used to simulate bots in isolation from the rest of the inst. Returns a promise that resolves with an object that contains all of the action functions.

  One of the special things about debug environments is that the bots in the environment are totally isolated from regular bots. This means that functions like getBots(...filters) can only access bots that have been created in the debugger and actions like os.toast(message, duration) don't do anything automatically. This can be useful for automated testing where you want to see what some bots will do without actually letting them do anything.

  Pausable debuggers allow you to set pause triggers (also known as breakpoints) that temporarily stop the debugger at a specific location in a listener and allows you to inspect the current state of the script. Pausable debuggers work like normal debuggers, except that some specific functions return promises instead of a result. This is because those functions can trigger user code that could trigger a pause. When this is possible, the debugger returns a promise to your host code so you can properly handle the pause. (See the examples below for more information)

  The returned object can be used to create/find bots in the debug environment and simulate interactions. The debug environment also contains several functions that make it easy to observe what has happened inside the environment and therefore determine if everything was performed correctly.

  The first parameter is a PausableDebuggerOptions and is the options that should be used to configure the debugger.

  Examples

  Create a pausable debugger

  const debug = await os.createDebugger({
      pausable: true
  });
  
  // Register a listener that gets called whenever a pause happens in this debugger.
  debug.onPause(pause => {
      // Get the current stack frame from the pause
      const currentFrame = pause.callStack[pause.callStack.length - 1];
  
      // Set the abc variable to 999
      currentFrame.setVariableValue('abc', 999);
  
      // Resume execution after the pause.
      debug.resume(pause);
  });
  
  // Because the debugger is pausable, the create() function returns a promise
  // because it calls

• os.getExecutingDebugger(): Debugger

  Gets the debugger that is currently executing the script. Returns null if the script is not running in a debugger.

  Examples

  Get the debugger that this script is running in

  const debug = os.getExecutingDebugger();
  console.log(debug);