> For the complete documentation index, see [llms.txt](https://docs.elentra.org/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elentra.org/api/automated-testing/functional-tests/annotations.md).

# Annotations

### Transaction Annotations

#### @transaction

```php
/**
* 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

```php
/**
* 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

{% hint style="warning" %}
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. 
{% endhint %}

#### @snapshot db

```php
/**
 * 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

```php
/**
  * 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. 

{% hint style="info" %}
The annotation `@snapshot db:table` also accepts wildcards\
For example: `@snapshot entrada:event%` will snapshot all tables that start with`event` in the ME database. 
{% endhint %}

### Seed Table Annotations

#### @seedTable table

```php
/**
* 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

```php
/**
* 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

```php
    /**
     * 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).

{% hint style="success" %}
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.
{% endhint %}