src/test/java/net/starlark/java/eval/StarlarkThreadDebuggingTest.java - bazel - Git at Google

 // Copyright 2018 The Bazel Authors. All Rights Reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //    http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.

 package net.starlark.java.eval;

 import static com.google.common.collect.ImmutableList.toImmutableList;
 import static com.google.common.truth.Truth.assertThat;
 import static org.junit.Assert.assertThrows;

 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Iterables;
 import javax.annotation.Nullable;
 import net.starlark.java.eval.Debug.ReadyToPause;
 import net.starlark.java.eval.Debug.Stepping;
 import net.starlark.java.syntax.FileOptions;
 import net.starlark.java.syntax.Location;
 import net.starlark.java.syntax.ParserInput;
 import net.starlark.java.syntax.SyntaxError;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;

 /** Tests of debugging features of StarlarkThread. */
 @RunWith(JUnit4.class)
 public class StarlarkThreadDebuggingTest {

   // TODO(adonovan): rewrite these tests at a higher level.

   private static StarlarkThread newThread() {
     return StarlarkThread.createTransient(Mutability.create("test"), StarlarkSemantics.DEFAULT);
   }

   // Executes the definition of a trivial function f and returns the function value.
   private static StarlarkFunction defineFunc() throws Exception {
     return (StarlarkFunction)
         Starlark.execFile(
             ParserInput.fromLines("def f(): pass\nf"),
             FileOptions.DEFAULT,
             Module.create(),
             newThread());
   }

   @Test
   public void testListFramesEmptyStack() {
     StarlarkThread thread = newThread();
     assertThat(Debug.getCallStack(thread)).isEmpty();
     assertThat(thread.getCallStack()).isEmpty();
   }

   /**
    * A callable which captures the Starlark call stack at the time of the last call to it.
    *
    * <p>In Starlark, returns the first positional arg if supplied, or None otherwise.
    */
   private static final class StackTracer implements StarlarkCallable {
     private final String name;
     // Debug.Frame values are mutable (and are expected to mutate during the execution of a thread),
     // so we capture their formatted string form instead. (The string form also makes test failures
     // more informative.)
     @Nullable private ImmutableList<String> debugStack;
     @Nullable private ImmutableList<StarlarkThread.CallStackEntry> liteStack;

     private StackTracer(String name) {
       this.name = name;
     }

     @Nullable
     public ImmutableList<String> getDebugStack() {
       return debugStack;
     }

     @Nullable
     public String getCallerDebugFrame() {
       return debugStack != null ? debugStack.get(debugStack.size() - 2) : null;
     }

     @Nullable
     public ImmutableList<StarlarkThread.CallStackEntry> getLiteStack() {
       return liteStack;
     }

     @Override
     public String getName() {
       return name;
     }

     @Override
     public Object call(StarlarkThread thread, Tuple args, Dict<String, Object> kwargs) {
       debugStack =
           Debug.getCallStack(thread).stream()
               .map(this::formatDebugFrame)
               .collect(toImmutableList());
       liteStack = thread.getCallStack();
       return Iterables.getFirst(args, Starlark.NONE);
     }

     private String formatDebugFrame(Debug.Frame fr) {
       return String.format(
           "%s @ %s local=%s", fr.getFunction().getName(), fr.getLocation(), fr.getLocals());
     }

     @Override
     public Location getLocation() {
       return Location.BUILTIN;
     }

     @Override
     public String toString() {
       return "<stack tracer>";
     }
   }

   @Test
   public void testListFramesFromBuiltin() throws Exception {
     // f is a built-in that captures the stack using the Debugger API.
     StackTracer f = new StackTracer("f");

     // Set up global environment.
     Module module =
         Module.withPredeclared(StarlarkSemantics.DEFAULT, ImmutableMap.of("a", 1, "b", 2, "f", f));

     // Execute a small file that calls f.
     ParserInput input =
         ParserInput.fromString(
             """
 def g(a, y, z):  # shadows global a
     f()

 g(4, 5, 6)
 """,
             "main.star");
     Starlark.execFile(input, FileOptions.DEFAULT, module, newThread());

     assertThat(f.getDebugStack())
         .containsExactly(
             // location is paren of g(4, 5, 6) call:
             "<toplevel> @ main.star:4:2 local={}",
             // location is paren of "f()" call:
             "g @ main.star:2:6 local={a=4, y=5, z=6}",
             // location is "current PC" in f.
             "f @ <builtin> local={}")
         .inOrder();

     // Same, with "lite" stack API.
     assertThat(f.getLiteStack().toString()) // an ImmutableList<StarlarkThread.CallStackEntry>
         .isEqualTo("[<toplevel>@main.star:4:2, g@main.star:2:6, f@<builtin>]");

     // TODO(adonovan): more tests:
     // - a stack containing functions defined in different modules.
     // - changing environment at various program points within a function.
   }

   @Test
   public void comprehensionVariables() throws Exception {
     // Tracers for capturing the stack using the Debugger API.
     StackTracer f = new StackTracer("f");
     StackTracer g = new StackTracer("g");
     StackTracer h = new StackTracer("h");
     StackTracer i = new StackTracer("i");
     StackTracer j = new StackTracer("j");
     StackTracer k = new StackTracer("k");

     Module module =
         Module.withPredeclared(
             StarlarkSemantics.DEFAULT,
             ImmutableMap.of("f", f, "g", g, "h", h, "i", i, "j", j, "k", k));

     ParserInput input =
         ParserInput.fromString(
             """
 def foo(x):
     x += [[j(x) for x in i(x)] + h(x) for x in f(x) if g(x)]
     return k(x)

 foo([[1]])
 """,
             "main.star");
     Starlark.execFile(input, FileOptions.DEFAULT, module, newThread());
     // f is in the outer comprehension's first for clause, and sees foo's local x
     assertThat(f.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:49 local={x=[[1]]}");
     // g and h see the outer comprehension's x
     assertThat(g.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:57 local={x=[1]}");
     assertThat(h.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:35 local={x=[1]}");
     // i is in the inner comprehension's first for clause, and so sees the outer comprehension's x
     assertThat(i.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:27 local={x=[1]}");
     // j sees the inner comprehension's x
     assertThat(j.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:13 local={x=1}");
     // k is outside the comprehensions' scope, and sees the final value of foo's local x
     assertThat(k.getCallerDebugFrame()).isEqualTo("foo @ main.star:3:13 local={x=[[1], [1, 1]]}");
   }

   @Test
   public void testStepIntoFunction() throws Exception {
     StarlarkThread thread = newThread();

     ReadyToPause predicate = Debug.stepControl(thread, Stepping.INTO);
     thread.push(defineFunc());

     assertThat(predicate.test(thread)).isTrue();
   }

   @Test
   public void testStepIntoFallsBackToStepOver() {
     // test that when stepping into, we'll fall back to stopping at the next statement in the
     // current frame
     StarlarkThread thread = newThread();

     ReadyToPause predicate = Debug.stepControl(thread, Stepping.INTO);

     assertThat(predicate.test(thread)).isTrue();
   }

   @Test
   public void testStepIntoFallsBackToStepOut() throws Exception {
     // test that when stepping into, we'll fall back to stopping when exiting the current frame
     StarlarkThread thread = newThread();
     thread.push(defineFunc());

     ReadyToPause predicate = Debug.stepControl(thread, Stepping.INTO);
     thread.pop();

     assertThat(predicate.test(thread)).isTrue();
   }

   @Test
   public void testStepOverFunction() throws Exception {
     StarlarkThread thread = newThread();

     ReadyToPause predicate = Debug.stepControl(thread, Stepping.OVER);
     thread.push(defineFunc());

     assertThat(predicate.test(thread)).isFalse();
     thread.pop();
     assertThat(predicate.test(thread)).isTrue();
   }

   @Test
   public void testStepOverFallsBackToStepOut() throws Exception {
     // test that when stepping over, we'll fall back to stopping when exiting the current frame
     StarlarkThread thread = newThread();
     thread.push(defineFunc());

     ReadyToPause predicate = Debug.stepControl(thread, Stepping.OVER);
     thread.pop();

     assertThat(predicate.test(thread)).isTrue();
   }

   @Test
   public void testStepOutOfInnerFrame() throws Exception {
     StarlarkThread thread = newThread();
     thread.push(defineFunc());

     ReadyToPause predicate = Debug.stepControl(thread, Stepping.OUT);

     assertThat(predicate.test(thread)).isFalse();
     thread.pop();
     assertThat(predicate.test(thread)).isTrue();
   }

   @Test
   public void testStepOutOfOutermostFrame() {
     StarlarkThread thread = newThread();

     assertThat(Debug.stepControl(thread, Stepping.OUT)).isNull();
   }

   @Test
   public void testStepControlWithNoSteppingReturnsNull() {
     StarlarkThread thread = newThread();

     assertThat(Debug.stepControl(thread, Stepping.NONE)).isNull();
   }

   @Test
   public void testEvaluateVariableInScope() throws Exception {
     Module module =
         Module.withPredeclared(StarlarkSemantics.DEFAULT, ImmutableMap.of("a", StarlarkInt.of(1)));

     StarlarkThread thread = newThread();
     Object a = Starlark.execFile(ParserInput.fromLines("a"), FileOptions.DEFAULT, module, thread);
     assertThat(a).isEqualTo(StarlarkInt.of(1));
   }

   @Test
   public void testEvaluateVariableNotInScopeFails() {
     Module module = Module.create();

     SyntaxError.Exception e =
         assertThrows(
             SyntaxError.Exception.class,
             () ->
                 Starlark.execFile(
                     ParserInput.fromLines("b"), FileOptions.DEFAULT, module, newThread()));

     assertThat(e).hasMessageThat().isEqualTo("name 'b' is not defined");
   }

   @Test
   public void testEvaluateExpressionOnVariableInScope() throws Exception {
     StarlarkThread thread = newThread();
     Module module =
         Module.withPredeclared(
             StarlarkSemantics.DEFAULT, /*predeclared=*/ ImmutableMap.of("a", "string"));

     assertThat(
             Starlark.execFile(
                 ParserInput.fromLines("a.startswith('str')"), FileOptions.DEFAULT, module, thread))
         .isEqualTo(true);
     Starlark.execFile(ParserInput.fromLines("a = 1"), FileOptions.DEFAULT, module, thread);
     assertThat(Starlark.execFile(ParserInput.fromLines("a"), FileOptions.DEFAULT, module, thread))
         .isEqualTo(StarlarkInt.of(1));
   }
 }
	// Copyright 2018 The Bazel Authors. All Rights Reserved.
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.

	package net.starlark.java.eval;

	import static com.google.common.collect.ImmutableList.toImmutableList;
	import static com.google.common.truth.Truth.assertThat;
	import static org.junit.Assert.assertThrows;

	import com.google.common.collect.ImmutableList;
	import com.google.common.collect.ImmutableMap;
	import com.google.common.collect.Iterables;
	import javax.annotation.Nullable;
	import net.starlark.java.eval.Debug.ReadyToPause;
	import net.starlark.java.eval.Debug.Stepping;
	import net.starlark.java.syntax.FileOptions;
	import net.starlark.java.syntax.Location;
	import net.starlark.java.syntax.ParserInput;
	import net.starlark.java.syntax.SyntaxError;
	import org.junit.Test;
	import org.junit.runner.RunWith;
	import org.junit.runners.JUnit4;

	/** Tests of debugging features of StarlarkThread. */
	@RunWith(JUnit4.class)
	public class StarlarkThreadDebuggingTest {

	// TODO(adonovan): rewrite these tests at a higher level.

	private static StarlarkThread newThread() {
	return StarlarkThread.createTransient(Mutability.create("test"), StarlarkSemantics.DEFAULT);
	}

	// Executes the definition of a trivial function f and returns the function value.
	private static StarlarkFunction defineFunc() throws Exception {
	return (StarlarkFunction)
	Starlark.execFile(
	ParserInput.fromLines("def f(): pass\nf"),
	FileOptions.DEFAULT,
	Module.create(),
	newThread());
	}

	@Test
	public void testListFramesEmptyStack() {
	StarlarkThread thread = newThread();
	assertThat(Debug.getCallStack(thread)).isEmpty();
	assertThat(thread.getCallStack()).isEmpty();
	}

	/**
	* A callable which captures the Starlark call stack at the time of the last call to it.
	*
	* <p>In Starlark, returns the first positional arg if supplied, or None otherwise.
	*/
	private static final class StackTracer implements StarlarkCallable {
	private final String name;
	// Debug.Frame values are mutable (and are expected to mutate during the execution of a thread),
	// so we capture their formatted string form instead. (The string form also makes test failures
	// more informative.)
	@Nullable private ImmutableList<String> debugStack;
	@Nullable private ImmutableList<StarlarkThread.CallStackEntry> liteStack;

	private StackTracer(String name) {
	this.name = name;
	}

	@Nullable
	public ImmutableList<String> getDebugStack() {
	return debugStack;
	}

	@Nullable
	public String getCallerDebugFrame() {
	return debugStack != null ? debugStack.get(debugStack.size() - 2) : null;
	}

	@Nullable
	public ImmutableList<StarlarkThread.CallStackEntry> getLiteStack() {
	return liteStack;
	}

	@Override
	public String getName() {
	return name;
	}

	@Override
	public Object call(StarlarkThread thread, Tuple args, Dict<String, Object> kwargs) {
	debugStack =
	Debug.getCallStack(thread).stream()
	.map(this::formatDebugFrame)
	.collect(toImmutableList());
	liteStack = thread.getCallStack();
	return Iterables.getFirst(args, Starlark.NONE);
	}

	private String formatDebugFrame(Debug.Frame fr) {
	return String.format(
	"%s @ %s local=%s", fr.getFunction().getName(), fr.getLocation(), fr.getLocals());
	}

	@Override
	public Location getLocation() {
	return Location.BUILTIN;
	}

	@Override
	public String toString() {
	return "<stack tracer>";
	}
	}

	@Test
	public void testListFramesFromBuiltin() throws Exception {
	// f is a built-in that captures the stack using the Debugger API.
	StackTracer f = new StackTracer("f");

	// Set up global environment.
	Module module =
	Module.withPredeclared(StarlarkSemantics.DEFAULT, ImmutableMap.of("a", 1, "b", 2, "f", f));

	// Execute a small file that calls f.
	ParserInput input =
	ParserInput.fromString(
	"""
	def g(a, y, z): # shadows global a
	f()

	g(4, 5, 6)
	""",
	"main.star");
	Starlark.execFile(input, FileOptions.DEFAULT, module, newThread());

	assertThat(f.getDebugStack())
	.containsExactly(
	// location is paren of g(4, 5, 6) call:
	"<toplevel> @ main.star:4:2 local={}",
	// location is paren of "f()" call:
	"g @ main.star:2:6 local={a=4, y=5, z=6}",
	// location is "current PC" in f.
	"f @ <builtin> local={}")
	.inOrder();

	// Same, with "lite" stack API.
	assertThat(f.getLiteStack().toString()) // an ImmutableList<StarlarkThread.CallStackEntry>
	.isEqualTo("[<toplevel>@main.star:4:2, g@main.star:2:6, f@<builtin>]");

	// TODO(adonovan): more tests:
	// - a stack containing functions defined in different modules.
	// - changing environment at various program points within a function.
	}

	@Test
	public void comprehensionVariables() throws Exception {
	// Tracers for capturing the stack using the Debugger API.
	StackTracer f = new StackTracer("f");
	StackTracer g = new StackTracer("g");
	StackTracer h = new StackTracer("h");
	StackTracer i = new StackTracer("i");
	StackTracer j = new StackTracer("j");
	StackTracer k = new StackTracer("k");

	Module module =
	Module.withPredeclared(
	StarlarkSemantics.DEFAULT,
	ImmutableMap.of("f", f, "g", g, "h", h, "i", i, "j", j, "k", k));

	ParserInput input =
	ParserInput.fromString(
	"""
	def foo(x):
	x += [[j(x) for x in i(x)] + h(x) for x in f(x) if g(x)]
	return k(x)

	foo([[1]])
	""",
	"main.star");
	Starlark.execFile(input, FileOptions.DEFAULT, module, newThread());
	// f is in the outer comprehension's first for clause, and sees foo's local x
	assertThat(f.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:49 local={x=[[1]]}");
	// g and h see the outer comprehension's x
	assertThat(g.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:57 local={x=[1]}");
	assertThat(h.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:35 local={x=[1]}");
	// i is in the inner comprehension's first for clause, and so sees the outer comprehension's x
	assertThat(i.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:27 local={x=[1]}");
	// j sees the inner comprehension's x
	assertThat(j.getCallerDebugFrame()).isEqualTo("foo @ main.star:2:13 local={x=1}");
	// k is outside the comprehensions' scope, and sees the final value of foo's local x
	assertThat(k.getCallerDebugFrame()).isEqualTo("foo @ main.star:3:13 local={x=[[1], [1, 1]]}");
	}

	@Test
	public void testStepIntoFunction() throws Exception {
	StarlarkThread thread = newThread();

	ReadyToPause predicate = Debug.stepControl(thread, Stepping.INTO);
	thread.push(defineFunc());

	assertThat(predicate.test(thread)).isTrue();
	}

	@Test
	public void testStepIntoFallsBackToStepOver() {
	// test that when stepping into, we'll fall back to stopping at the next statement in the
	// current frame
	StarlarkThread thread = newThread();

	ReadyToPause predicate = Debug.stepControl(thread, Stepping.INTO);

	assertThat(predicate.test(thread)).isTrue();
	}

	@Test
	public void testStepIntoFallsBackToStepOut() throws Exception {
	// test that when stepping into, we'll fall back to stopping when exiting the current frame
	StarlarkThread thread = newThread();
	thread.push(defineFunc());

	ReadyToPause predicate = Debug.stepControl(thread, Stepping.INTO);
	thread.pop();

	assertThat(predicate.test(thread)).isTrue();
	}

	@Test
	public void testStepOverFunction() throws Exception {
	StarlarkThread thread = newThread();

	ReadyToPause predicate = Debug.stepControl(thread, Stepping.OVER);
	thread.push(defineFunc());

	assertThat(predicate.test(thread)).isFalse();
	thread.pop();
	assertThat(predicate.test(thread)).isTrue();
	}

	@Test
	public void testStepOverFallsBackToStepOut() throws Exception {
	// test that when stepping over, we'll fall back to stopping when exiting the current frame
	StarlarkThread thread = newThread();
	thread.push(defineFunc());

	ReadyToPause predicate = Debug.stepControl(thread, Stepping.OVER);
	thread.pop();

	assertThat(predicate.test(thread)).isTrue();
	}

	@Test
	public void testStepOutOfInnerFrame() throws Exception {
	StarlarkThread thread = newThread();
	thread.push(defineFunc());

	ReadyToPause predicate = Debug.stepControl(thread, Stepping.OUT);

	assertThat(predicate.test(thread)).isFalse();
	thread.pop();
	assertThat(predicate.test(thread)).isTrue();
	}

	@Test
	public void testStepOutOfOutermostFrame() {
	StarlarkThread thread = newThread();

	assertThat(Debug.stepControl(thread, Stepping.OUT)).isNull();
	}

	@Test
	public void testStepControlWithNoSteppingReturnsNull() {
	StarlarkThread thread = newThread();

	assertThat(Debug.stepControl(thread, Stepping.NONE)).isNull();
	}

	@Test
	public void testEvaluateVariableInScope() throws Exception {
	Module module =
	Module.withPredeclared(StarlarkSemantics.DEFAULT, ImmutableMap.of("a", StarlarkInt.of(1)));

	StarlarkThread thread = newThread();
	Object a = Starlark.execFile(ParserInput.fromLines("a"), FileOptions.DEFAULT, module, thread);
	assertThat(a).isEqualTo(StarlarkInt.of(1));
	}

	@Test
	public void testEvaluateVariableNotInScopeFails() {
	Module module = Module.create();

	SyntaxError.Exception e =
	assertThrows(
	SyntaxError.Exception.class,
	() ->
	Starlark.execFile(
	ParserInput.fromLines("b"), FileOptions.DEFAULT, module, newThread()));

	assertThat(e).hasMessageThat().isEqualTo("name 'b' is not defined");
	}

	@Test
	public void testEvaluateExpressionOnVariableInScope() throws Exception {
	StarlarkThread thread = newThread();
	Module module =
	Module.withPredeclared(
	StarlarkSemantics.DEFAULT, /predeclared=/ ImmutableMap.of("a", "string"));

	assertThat(
	Starlark.execFile(
	ParserInput.fromLines("a.startswith('str')"), FileOptions.DEFAULT, module, thread))
	.isEqualTo(true);
	Starlark.execFile(ParserInput.fromLines("a = 1"), FileOptions.DEFAULT, module, thread);
	assertThat(Starlark.execFile(ParserInput.fromLines("a"), FileOptions.DEFAULT, module, thread))
	.isEqualTo(StarlarkInt.of(1));
	}
	}