# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.elentra.org/api/automated-testing/functional-tests/annotations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.