Annotations

Elentra's API contains custom annotations for functional tests that help developers easily create and manage tests.

Transaction Annotations

@transaction

/**
* Test that the route [GET] /exams/questions/groups/authors return 200
*
* @test
* @transaction
* @return void
*/
public function exams_get_method_exams_questions_groups_authors_returns_200(): void
{
  $this->actingAsAdmin()
      ->authenticate()
      ->get('/exams/questions/groups/authors')

The transaction annotation restores all database tables in Elentra.

@transaction db

/**
* Test that the route [GET] /exams/questions/groups/authors return 200
*
* @test
* @transaction entrada
* @return void
*/
public function exams_get_method_exams_questions_groups_authors_returns_200(): void
{
  $this->actingAsAdmin()
      ->authenticate()
      ->get('/exams/questions/groups/authors')

When the transaction is passed a database name, it only restores that database's tables.

Snapshot Annotations

Snapshot performance is slow; therefore, this should only be used when the transaction annotation will not work. This happens when the endpoint relies on ME code that uses AdoDB, which would use a separate DB connection from Laravel.

@snapshot db

/**
 * Test that the route [PUT] /assessments/tasks/{task_id}/remove returns 200
 *
 * @snapshot entrada
 * @test
 * @return void
 */
public function assessments_put_method_tasks_task_remove_returns_200(): void
{
    $this->actingAsAdmin()
        ->authenticate()
        ->put('/assessments/tasks/1/remove', [
            'task_id' => 1,
        ])

This will snapshot the entire database and then restore it after the test has run.

@snapshot db:table

/**
  * Test that the route POST /messaging/update_my_attendance returns 200
  *
  * @snapshot entrada:event_attendance
  * @test
  * @return void
  */
 public function messaging_controller_post_method_update_my_attendance_returns_200(): void
 {
     $this->actingAs(User::find(UsersSeedData::ALTERNATE_STUDENT_ID)) // one of the event attendance audience
         ->authenticate()
         ->post('/messaging/update_my_attendance', [
             'event_id' => EventsSeedData::BASE_EVENT_ID,
         ])

This will only snapshot and restore the specific table in the given database.

The annotation @snapshot db:table also accepts wildcards For example: @snapshot entrada:event% will snapshot all tables that start withevent in the ME database.

Seed Table Annotations

@seedTable table

/**
* Test that the route [GET] /exams/questions/groups/authors return 200
*
* @test
* @seedTable exam_questions
* @return void
*/
public function exams_get_method_exams_questions_groups_authors_returns_200(): void
{
  $this->actingAsAdmin()
      ->authenticate()
      ->get('/exams/questions/groups/authors')

This will truncate the table and then find the given seeder in order to seed the table again.

@seedTable db:table

/**
* Test that the route [GET] /exams/questions/groups/authors returns 200
*
* @test
* @seedTable entrada:exam_questions
* @return void
*/
public function exams_get_method_exams_questions_groups_authors_returns_200(): void
{
  $this->actingAsAdmin()
      ->authenticate()
      ->get('/exams/questions/groups/authors')

This will truncate the exam_questions table within the ME database, find the given seeder, and seed the table again.

Drop Table Annotations

@dropTable db:table

    /**
     * Test that the route [POST] /cbe/trees/{tree_id}/trunk/versions/course returns 201
     *
     * @test
     * @snapshot cbe
     *
     * This request creates a table that is not dropped by snapshot, so drop it after the test runs
     * @dropTable cbe:cbe_trees_2_course_3_version_3
     *
     * @see store
     * @return void
     */
    public function cbe_objective_trees_post_method_trunk_versions_course_returns_201(): void
    {
        $this->actingAsAdmin()
            ->authenticate()
            ->post('/cbe/trees/2/trunk/versions/course?tree_id=2&curriculum_framework_id=1', [])
            ->assertCreated()

The @dropTable annotation will run DROP IF EXISTS on the specified table(s) in the specified schema(s).

This is particularly useful when the endpoint creates a new table not already in the schema, and we need to remove that table for subsequent tests to execute successfully.