The WPILib command framework divides your robot program into two types of classes: subsystems and commands. The subsystem classes represent the major physical parts of the robot, such as a shooter subsystem, a drive-train subsystem, or a manipulator arm subsystem. The command classes define the actions taken by the subsystems, such as shooting a ball, moving the drive-train, or raising the manipulator arm.
Most of your programming time will go into creating, refining and debugging new commands. Commands will be the most sophisticated part of your code. Therefore they also have the greatest risk of going wrong. Therefore you should spend a lot of time testing your commands.
So far we have tested simple functions and verified the primitive functionality in subsystems. The next step is to created automated tests for your commands.
Testing a simple Command
Our simple example robot contains a Shooter subsystem that shoots balls. The ShooterSubsystem has a high-speed wheel for throwing the ball, and a servo arm that can raise the ball up until it touches the wheel. We will need a command to set the wheel speed, and another to control the servo arm.
A simple Command
Here is the command to raise or lower the servo arm:
package frc.robot.commands;
import edu.wpi.first.wpilibj.experimental.command.*;
import frc.robot.subsystems.*;
public class ShooterServoArmCommand extends SendableCommandBase {
private final boolean fire;
private final ShooterSubsystem shooter;
public ShooterServoArmCommand(boolean fireArm, ShooterSubsystem shooterSubsystem) {
fire = fireArm;
shooter = shooterSubsystem;
addRequirements(shooter);
}
@Override
public void execute() {
if (fire) {
shooter.fire();
} else {
shooter.retract();
}
}
@Override
public boolean isFinished() {
return true;
}
}
Take note of the two parameters on the constructor: fireArm and shooterSubsystem. This command can either raise the arm or lower it, depending on whether the fireArm parameter is true or false.
By specifying the shooterSubsytem in the constructor we are using Dependency Injection, which makes the code more reusable and more testable. When testing, we can replace the real subsystems with mock objects that fake the subsystem’s functionality.
A simple Test
Our task does two different things: retract and fire. First let’s test that firing the ball works:
package frc.robot.commands;
import edu.wpi.first.wpilibj.experimental.command.*;
import frc.robot.subsystems.*;
import org.junit.*;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
public class ShooterServoArmCommandTest {
private CommandScheduler scheduler = null;
@Before
public void setup() {
scheduler = CommandScheduler.getInstance();
}
@Test
public void testFireArm() {
// Arrange
ShooterSubsystem shooter = mock(ShooterSubsystem.class);
ShooterServoArmCommand fireCommand
= new ShooterServoArmCommand(true, shooter);
// Act
scheduler.schedule(fireCommand);
scheduler.run();
// Assert
verify(shooter).fire();
}
}
The test follows our Arrange / Act / Assert pattern:
- We create a mock version of our ShooterSubsystem. If we wanted, we could also define some mock behaviors at this point.
We create the actual command we will test. In this case we set the fireArm parameter to true, indicating that we want to fire the ball. - In the command framework, we never explicitly execute the command methods. Instead, we “put it on the schedule”. After this, the command scheduler will run the methods appropriately. On a real robot, the scheduler tries to run all scheduled commands every 20 milliseconds.
In this case we know that our command will only run once before it’s done. - At the end of the test, we ask the mock framework to verify that the shooter’s “fire” command was called exactly once.
Unit tests will all execute whenever we build the code. Go ahead and execute the “Build Robot Code” action within Visual Studio code. Next write a similar test to verify that the command also correctly retracts the servo arm:
@Test
public void testRetractArm() {
// Arrange
ShooterSubsystem shooter = mock(ShooterSubsystem.class);
ShooterServoArmCommand retractCommand = new ShooterServoArmCommand(false, shooter);
// Act
scheduler.schedule(retractCommand);
scheduler.run();
// Assert
verify(shooter).retract();
}
Testing a Command Group
Simple commands can be grouped together to run sequentially or in parallel as more complicated commands.
A more complex Command
For instance, actually shooting a ball is a sequence of steps:
package frc.robot.commands;
import edu.wpi.first.wpilibj.experimental.command.*;
import frc.robot.subsystems.*;
public class AutoShootCommand extends SequentialCommandGroup {
public AutoShootCommand(ShooterSubsystem shooter) {
super(
new PrintCommand("BEGIN: AutoShootCommand"),
new ShooterServoArmCommand(false, shooter),
new ShooterSetSpeedCommand(1.0, shooter),
new WaitCommand(0.5),
new ShooterServoArmCommand(true, shooter),
new WaitCommand(0.5),
new ShooterSetSpeedCommand(0.0, shooter),
new ShooterServoArmCommand(false, shooter),
new PrintCommand("END: AutoShootCommand")
);
}
}
Note that we are again using dependency injection, but that the same ShooterSubsystem will be used in all the internal commands.
Besides the shooter commands, we’ve also thrown in a couple of PrintCommands. These commands print out to the console at the beginning and end of the command. They also print to the Log File Viewer to be reviewed after a match.
Also we’ve thrown in a couple of WaitCommands, which give the shooter wheel half a second to spin up before shooting and then maintain speed while the ball is firing.
Testing a Command Group
A command group test follows the same pattern as simpler tests:
package frc.robot.commands;
import static org.junit.Assert.*;
import static org.mockito.Mockito.*;
import org.junit.*;
import edu.wpi.first.wpilibj.experimental.command.CommandScheduler;
import frc.robot.subsystems.ShooterSubsystem;
public class AutoShootCommandTest {
private CommandScheduler scheduler = null;
@Before
public void setup() {
scheduler = CommandScheduler.getInstance();
}
@Test
public void testShoot() throws InterruptedException {
// Arrange
ShooterSubsystem shooter = mock(ShooterSubsystem.class);
AutoShootCommand command = new AutoShootCommand(shooter);
// Act
scheduler.schedule(command);
for (int i=0; i<100; i++) {
scheduler.run();
Thread.sleep(20);
}
// Assert
verify(shooter, times(2)).retract();
verify(shooter, times(1)).fire();
verify(shooter).setSpeed(1.0);
verify(shooter).setSpeed(0.0);
}
}
This command takes many run cycles, so run it many times, pausing 20 milliseconds between each execution.
After executing everything in the command group, we verify that the subsystem experienced all the actions for shooting.
Writing quality tests
It’s important to remember why we do unit testing.: we create suites of automated tests to improve the quality of our software. Writing quality tests is a big subject and these last three articles have covered a lot of ground. It would be easy to be overwhelmed, or in fact dubious, with all of this. So keep your eye on the end goal: software quality.
In a sense, writing methodical tests is a stepping stone from just programming into Software Engineering. Engineering means using systematic and disciplined practices when creating things. Your tests will verify and quantify your software quality, in way that others can read and evaluate.
FirstMnCsa 