# TCMS — Test Environment Management: Complete Guide
### For Administrators and QC Team Members

---

## Table of Contents

1. [What Is This Feature? (Plain English)](#1-what-is-this-feature-plain-english)
2. [Key Concepts — Explained Simply](#2-key-concepts--explained-simply)
3. [Who Does What? (Roles)](#3-who-does-what-roles)
4. [How the Full Flow Works (End-to-End)](#4-how-the-full-flow-works-end-to-end)
5. [Setup Guide for Administrators](#5-setup-guide-for-administrators)
6. [QC Daily Workflow — Step by Step](#6-qc-daily-workflow--step-by-step)
7. [Adding a New Feature to Test](#7-adding-a-new-feature-to-test)
8. [Reading Reset History (Audit Trail)](#8-reading-reset-history-audit-trail)
9. [CI Pipeline — How Automated Testing Uses This](#9-ci-pipeline--how-automated-testing-uses-this)
10. [Troubleshooting Common Problems](#10-troubleshooting-common-problems)
11. [Quick Reference Card](#11-quick-reference-card)

---

## 1. What Is This Feature? (Plain English)

### The Problem It Solves

Imagine you are a QC tester working on the "Purchase Order" module. You run a test that creates 50 dummy purchase orders, updates them, and deletes some. Now the database has leftover data from your test. The next tester who runs the same test finds old records they didn't create — their test results become unreliable.

Or: you are testing the payroll module and you accidentally delete the salary structure for an employee. Now other tests that depend on that employee's data will also fail — even though those tests have nothing to do with what you were testing.

**The core problem: test databases get messy and polluted over time.**

### What This Feature Does

The TCMS Test Environment Management feature gives the QC team a way to:

1. **Set up clean, dedicated test databases** — separate from the real (production) database
2. **Take a "snapshot" (photograph) of a database at a known-good state** before running tests
3. **Restore that snapshot instantly** after tests are done, wiping out all test pollution
4. **Clone a control copy** of the database whenever a completely fresh start is needed
5. **See a full history** of every reset and sync operation (audit trail)

### A Simple Analogy

Think of it like a **video game save file**:

- The **Control Database** = the original, untouched game master copy
- The **Run/Test Database** = a copy you actually play on
- A **Snapshot** = a save file at a checkpoint (e.g., just before a boss fight)
- **Restore Snapshot** = loading that save file to go back to exactly that moment
- **Sync from Control** = throwing away your current game file and starting fresh from the master copy
- **Clone from Control** = making a brand-new copy of the master to give to a new player

---

## 2. Key Concepts — Explained Simply

### 2.1 Control Database

The **Control Database** is the "gold master" — a carefully maintained database that contains:
- A realistic set of master data (customers, employees, chart of accounts, etc.)
- No test pollution (no half-finished transactions, no dummy data from previous test runs)
- Usually maintained by the Database Administrator (DBA)

> **Example:** `GB_CONTROL_DB` has 50 real-looking customers, 200 employees, and a complete chart of accounts — enough data to run any test realistically, but nothing left over from previous tests.

**You never run your tests directly against the Control Database.** It's read-only for QC purposes. The admin clones it to create test databases.

---

### 2.2 Run Database (Test Database)

The **Run Database** (also called Test DB or Run DB) is the actual database your tests write to. Each team, module, or CI pipeline job gets its own Run Database so they don't interfere with each other.

> **Example:** The "Finance QC Team" might have a run database called `GB_RUN_FINANCE_QC`. The "Payroll CI Pipeline" might have one called `GB_RUN_PAYROLL_CI`.

---

### 2.3 Snapshot

A **Snapshot** is a frozen copy of the Run Database at a specific point in time. Think of it as pressing the "Save" button in a video game.

> **Example:** Before you start testing the "Month-End Close" process, you take a snapshot called `"before-month-end-june"`. After your tests are done (or if something goes wrong), you can restore this snapshot and the database goes back to exactly the state it was in when you pressed Save.

**Important:** Snapshots are fast to create and restore — typically seconds to a few minutes, not hours.

---

### 2.4 Clone from Control

**Cloning** creates a brand-new Run Database by copying the Control Database. This gives you a completely fresh start — not just restoring a snapshot, but going back to the master copy itself.

> **Example:** You've been running tests for 3 weeks and even your snapshots are getting stale (because the control database was updated with new master data last week). An admin runs "Clone from Control" to create a brand-new `GB_RUN_FINANCE_QC` database from the latest control copy. Now your run database is perfectly in sync with the control.

**Cloning takes longer** than restoring a snapshot (could be minutes to tens of minutes depending on database size).

---

### 2.5 Sync from Control

**Sync** is similar to Clone but instead of creating a new database, it **replaces the contents** of an existing Run Database with the contents of the Control Database.

> **Example:** The Control Database was updated with 10 new employee records added by the HR team. You run "Sync from Control" on your `GB_RUN_FINANCE_QC` to pull in those new records without having to register and re-configure the database.

**Note:** Sync is a destructive operation — it wipes out everything in the Run Database and replaces it. Make sure you have saved a snapshot first if you want to keep any test data.

---

### 2.6 Connection Details

The **Connection Details** are the technical credentials needed to connect to the test database directly (for example, using a tool like SQL Server Management Studio, DBeaver, or pgAdmin). This includes:

- Server IP address
- Database name
- Username and Password
- Port number (for PostgreSQL)

> **Why you might need this:** If a test fails and you want to manually inspect the database to understand what happened, you'd use the connection details to connect directly.

**Security note:** Connection details (especially the password) are sensitive. The system shows them only in a secure pop-up dialog and never displays the password as plain text on screen.

---

## 3. Who Does What? (Roles)

### Administrator (DBA / DevOps)

Administrators set up and maintain the test environments. Their responsibilities:

| Task | When |
|------|------|
| Register a new Test Database | When a new team or pipeline needs a test DB |
| Clone from Control | When a team needs a completely fresh start |
| Sync from Control | When the Control DB has been updated with new master data |
| Create initial Snapshots | After setting up, before QC starts testing |
| Deregister a Test Database | When a team no longer needs their test DB |
| Monitor Reset History | Audit trail and troubleshooting |

### QC Team Member

QC team members use the environments set up by the Admin. Their day-to-day responsibilities:

| Task | When |
|------|------|
| Take a Snapshot | Before starting a test run |
| Restore a Snapshot | After a test run, or to reset to a known state |
| Create a Snapshot | To bookmark a stable state mid-testing |
| View Reset History | To understand when the database was last reset |
| Request a Snapshot/Sync | Ask the Admin if a fresh clone is needed |

> **Rule of thumb:** Admins build the garage; QC team parks and drives the cars.

---

## 4. How the Full Flow Works (End-to-End)

Here is a visual walkthrough of the complete lifecycle:

```
ADMIN SETUP PHASE
─────────────────
1. Admin registers Test DB
   (connects it to TCMS, gives it a name)
         │
         ▼
2. Admin clones Control DB → Run DB
   ("fresh copy" operation)
         │
         ▼
3. Admin creates initial snapshot
   ("pre-test-clean" bookmark)
         │
         ▼
TEST EXECUTION PHASE
────────────────────
4. QC member checks current state
   (looks at TCMS Test Env list)
         │
         ▼
5. QC member restores snapshot
   (database is now in known-good state)
         │
         ▼
6. QC member runs test cases
   (tests write/update/delete data)
         │
         ▼
7. QC member checks results & logs
         │
         ▼
8. QC member restores snapshot again
   (clean up after the test run)
         │
         ▼
MAINTENANCE PHASE (as needed)
──────────────────────────────
9. Admin syncs from Control
   (when master data changes)
         │
         ▼
10. Admin creates new snapshots
    (new "save points" after sync)
```

---

## 5. Setup Guide for Administrators

This section walks you through setting up a complete test environment from scratch. No experience required.

---

### Step 1: Navigate to the Test Environment Page

1. Open the TCMS application in your browser
2. In the left sidebar or navigation menu, click **"Test Environments"** (or navigate to `/testenv` in the URL)
3. You will see the **Test Environment Management** screen

At first, the table will be empty — that's normal if no environments have been set up yet.

---

### Step 2: Register a New Test Database

"Registering" tells TCMS that a database exists and should be managed. The database should already exist on the server before you register it. If it doesn't exist yet, you'll create it via the Clone step.

1. Click the **"Register Test DB"** button (top-right area of the screen)
2. A form will slide open at the bottom. Fill in:

   | Field | What to Enter | Example |
   |-------|---------------|---------|
   | **Connection Name** | A friendly label for this environment | `Finance QC - Sprint 42` |
   | **Server** | Select from the dropdown list of known servers | `DB-SERVER-01 (192.168.1.10)` |
   | **Database Name** | The exact name of the database on that server | `GB_RUN_FINANCE_S42` |
   | **Database Type** | What kind of database it is | `SQL Server` or `PostgreSQL` |
   | **Control Source DB Name** | The name of the Control Database on the same server | `GB_CONTROL_MAIN` |
   | **Username** | The database login username | `gb_testuser` |
   | **Password** | The database login password | `(enter the password)` |
   | **Port** | Only needed for PostgreSQL; leave blank for SQL Server | `5432` (PostgreSQL) or blank (SQL Server) |

3. Click **"Register"**
4. If successful, the new database appears in the table
5. If you get an error, check that the Server, Database Name, Username, and Password are all correct

> **Example — what a filled form looks like:**
> - Connection Name: `Payroll QC Environment`
> - Server: `DB-TESTSERVER-02 (10.0.1.55)`
> - Database Name: `GB_RUN_PAYROLL_QC`
> - Database Type: `SQL Server`
> - Control Source DB: `GB_CONTROL_HR`
> - Username: `payroll_tester`
> - Password: `P@ssw0rd_QC_2024`
> - Port: (blank — SQL Server doesn't need this)

---

### Step 3: Clone from Control (First-Time Setup)

After registering, the Run Database might be empty or contain old data. Cloning from Control gives you a clean, populated starting point.

> ⚠️ **Warning:** Cloning is a long-running operation. It could take **2–30 minutes** depending on database size. A spinning loader will appear — do not close the browser tab.

1. Click the **"Clone from Control"** button (next to "Register Test DB" in the toolbar)
2. Fill in the clone form:

   | Field | What to Enter | Example |
   |-------|---------------|---------|
   | **Control DB Name** | The Control Database to copy from | `GB_CONTROL_MAIN` |
   | **Run DB Name** | The target Run Database to copy into | `GB_RUN_FINANCE_QC` |
   | **Connection Name** | What this cloned environment should be called in TCMS | `Finance QC - Cloned June 2024` |

3. Read the warning banner: *"This operation clones the entire control database. It may take several minutes."*
4. Click **"Clone"**
5. The spinner appears — wait until the success notification ("Clone complete") appears
6. The table refreshes automatically. You will see the new entry with the "Last Reset" column updated

---

### Step 4: Create the Initial Snapshot ("The Checkpoint")

After cloning, the database is in a perfect known-good state. Capture it as a snapshot **before anyone runs any tests**. This is your safety net.

1. In the Test Environments table, find your newly cloned environment
2. Click the **camera icon** (📷) in the Actions column — this opens the Snapshots panel
3. You'll see a text box labelled "Snapshot Label" — type a descriptive name:
   - Good names: `"pre-test-clean"`, `"after-clone-june-2024"`, `"sprint-42-baseline"`
   - Bad names: `"test1"`, `"snapshot"`, `"abc"` (not descriptive enough)
4. Click **"Create Snapshot"**
5. A success notification appears and the snapshot appears in the list below

> **Example:** After cloning `GB_RUN_FINANCE_QC` from `GB_CONTROL_MAIN`, create a snapshot called `"baseline-pre-sprint42"`. This becomes the starting point for all Sprint 42 test runs.

---

### Step 5: Share Connection Details with the QC Team

The QC team may need to connect to the test database directly (for debugging). You can share the connection string securely:

1. Find the environment in the table
2. Click the **key icon** (🔑) in the Actions column
3. A secure dialog pops up showing all connection details
4. The password is hidden (dots) by default — click the eye icon to reveal it temporarily
5. Click **"Copy Connection String"** to copy a ready-to-use connection string to the clipboard
6. Share this string with the QC team via your secure communication channel (not email)

> ⚠️ **Never paste the connection string (with password) into a ticket, email, or chat message. Use your team's secure password manager or vault.**

---

## 6. QC Daily Workflow — Step by Step

This section is for QC team members who are about to run tests. Follow this every time.

---

### Before You Start Testing

#### Step 1: Check the Current State of Your Environment

1. Open TCMS → **Test Environments**
2. Find your team's environment in the table (e.g., `Finance QC Environment`)
3. Check the **"Last Reset"** column — it shows when the database was last restored/synced and by whom
4. Check if the database is marked **Stale** (shown with slightly faded/greyed text) — this means it hasn't been synced in a while

If the database looks old or you're unsure of its state, proceed to restore a snapshot.

---

#### Step 2: Restore the Baseline Snapshot

This is the most important step — it gives you a clean database guaranteed to be in the correct state.

1. Click the **camera icon** (📷) next to your environment
2. The Snapshots panel opens at the bottom
3. Find the snapshot you want to restore (usually the baseline, e.g., `"baseline-pre-sprint42"`)
4. Click the **restore icon** (↩️) next to that snapshot
5. A confirmation message appears: *"Restore to snapshot 'baseline-pre-sprint42'? This will replace all current database contents."*
6. Click **"Restore"**
7. Wait for the spinner to finish (this takes 1–5 minutes for most databases)
8. Success message appears: *"Restore complete"*

> ✅ **Your database is now in a clean, known state. You're ready to test.**

> ⚠️ **Restore is destructive.** Any data added to the database after the snapshot was taken will be gone. This is intentional — that's the whole point.

---

#### Step 3: Take Your Own Snapshot (Optional but Recommended)

If you want to be able to go back to a mid-test state, take a snapshot before each major test block:

- Before testing "Create Purchase Order" → snapshot: `"before-po-creation-tests"`
- Before testing "Month-End Close" → snapshot: `"before-month-end-june"`

This lets you restore to any of these points without having to go all the way back to the baseline.

---

### Running Tests

No special TCMS interaction needed while your tests are running. The tests write to your Run Database normally.

If a test fails midway and corrupts the database state: just restore your most recent snapshot and start again. You don't need to involve the Admin.

---

### After Your Test Run

#### Option A: Restore the Baseline Snapshot (Recommended)

Return the database to the baseline so the next tester starts clean.

1. Camera icon → find `"baseline-pre-sprint42"` → restore → confirm

#### Option B: Create a New Snapshot of Post-Test State

If the test created specific data you want to reuse in the next test session:

1. Camera icon → type label `"after-po-testing-session-1"` → Create Snapshot

This saves the current state for your next session.

---

### Example: Full QC Day Walkthrough

**Scenario:** Ravi (QC Engineer) is testing the "Expense Claim Approval" workflow for Sprint 43.

```
9:00 AM — Ravi opens TCMS Test Environments
           Finds "Finance QC - Sprint 43" environment
           Last Reset: yesterday at 5 PM by Admin (looks fresh — good!)

9:02 AM — Ravi clicks the Camera icon on "Finance QC - Sprint 43"
           Sees snapshot "sprint43-baseline" created by Admin
           Clicks Restore on "sprint43-baseline"

9:03 AM — Restore in progress (spinner shown)

9:06 AM — "Restore complete" notification appears
           Database is now in the Sprint 43 baseline state

9:06 AM — Ravi takes a personal snapshot: "ravi-start-expense-claim-tests"
           (just in case something goes wrong)

9:07 AM — 12:00 PM — Ravi runs 45 test cases for Expense Claim Approval
           Some tests pass, 3 fail (he investigates)

12:00 PM — Ravi finds a bug in Test Case TC-089
            He wants to re-run TC-089 from scratch
            He restores "ravi-start-expense-claim-tests"

12:03 PM — Database is back to 9:06 AM state
            Ravi re-runs TC-089 with fresh data — confirms the bug

12:30 PM — Ravi is done for the morning
            He restores "sprint43-baseline" 
            (so the afternoon session or other teammates start clean)
```

---

## 7. Adding a New Feature to Test

When a new feature (module, screen, or workflow) is being developed, the QC team needs to set up the test environment to support testing it. Here's what that involves.

---

### Scenario: New Feature — "Multi-Currency Purchase Orders"

The development team has added a new "Multi-Currency Purchase Orders" feature. The QC team needs to test it.

---

### Step 1: Confirm the Control Database Has the Required Master Data

The Control Database needs to have the currency master data (USD, EUR, GBP, etc.) already set up — otherwise your tests will fail because the data doesn't exist.

1. Ask the **Admin or DBA** to verify that `GB_CONTROL_MAIN` contains the Currency master table with the required entries
2. If it doesn't, the DBA adds the data to the Control Database (this is not done in TCMS — it's done directly by the DBA in the database)

---

### Step 2: Sync the Run Database from Control

Once the Control Database has the new master data (currencies), you need to pull that into your Run Database.

1. In TCMS Test Environments, find your environment
2. Click the **sync icon** (🔄) in the Actions column
3. A confirmation message appears: *"Sync Finance QC from control? This replaces all current data."*
4. Click **"Confirm"**
5. Wait for the spinner (2–15 minutes)
6. Success — your Run Database now has the currency master data

> ⚠️ **Sync wipes your Run Database and replaces it with the Control Database.** Any test data you had is gone. If you had snapshots, those are still there — but a snapshot of old data won't have the new currencies either.

---

### Step 3: Create a New Baseline Snapshot

After the sync, your database has the correct starting state for multi-currency testing. Take a new baseline snapshot immediately:

1. Camera icon → Label: `"sprint44-multicurrency-baseline"` → Create Snapshot

---

### Step 4: Create Feature-Specific Snapshots

Before each test block, create snapshots that describe the pre-condition:

| Before Testing... | Take Snapshot Named... |
|-------------------|----------------------|
| Creating POs in USD | `"before-usd-po-tests"` |
| Creating POs in EUR | `"before-eur-po-tests"` |
| Currency conversion rounding | `"before-fx-rounding-tests"` |
| Multi-currency approval workflow | `"before-multicur-approval-tests"` |

---

### Step 5: Map Test Cases to Snapshots

In your test plan / TCMS test cases, document which snapshot each test case needs:

| Test Case ID | Snapshot to Restore Before Running |
|-------------|-------------------------------------|
| TC-101 | `sprint44-multicurrency-baseline` |
| TC-102 | `before-usd-po-tests` |
| TC-103 | `before-eur-po-tests` |
| TC-110 | `before-multicur-approval-tests` |

This makes your tests repeatable — anyone can run TC-102 by restoring that one snapshot and running the test.

---

### Step 6: Test Execution

Run tests in order, restoring the appropriate snapshot before each group:

```
Restore "sprint44-multicurrency-baseline"
  → Run TC-101 (verify currencies loaded correctly)
  → Pass ✓

Restore "before-usd-po-tests"
  → Run TC-102 (create PO in USD)
  → Pass ✓

Restore "before-eur-po-tests"
  → Run TC-103 (create PO in EUR)
  → Fail ✗ → raise defect → restore again → verify fix → Pass ✓
```

---

### Step 7: Tear Down After Feature Testing Is Complete

Once the feature is signed off:

1. Restore the baseline snapshot to leave the environment clean for the next sprint
2. Old feature-specific snapshots can be deleted to free up disk space:
   - Camera icon → find old snapshot → Delete icon → Confirm

---

## 8. Reading Reset History (Audit Trail)

Every time a Sync, Clone, or Restore operation runs, it is recorded in the Reset History. This is useful for:

- Understanding when and why the database changed state
- Debugging unexpected test failures ("the data was fine yesterday — what changed?")
- Audit and compliance purposes

### How to Read the History

1. Find the environment in the Test Environments table
2. Click the **history icon** (🕐) in the Actions column
3. The History panel opens at the bottom of the screen

The table shows:

| Column | What It Means | Example |
|--------|---------------|---------|
| **Triggered By** | Who initiated the reset | `admin`, `ravi.kumar`, `ci-pipeline` |
| **Triggered On** | Date and time of the operation | `Jun 5, 2024, 9:02 AM` |
| **Control Source** | Which Control DB was used as the source | `GB_CONTROL_MAIN` |
| **Duration** | How long the operation took | `45,231 ms` (= 45 seconds) |
| **Status** | Did it succeed or fail? | Green "Success" or Red "Failed" |
| **Error Message** | If it failed, why | `"Control database not reachable"` |

### Example — Troubleshooting with History

**Problem:** Aisha (QC Engineer) ran test TC-089 at 10 AM and found data that shouldn't exist. She's confused because she restored the baseline snapshot at 9 AM.

**Investigation using History:**

1. Aisha opens the history for her environment
2. She sees:

   | Triggered By | Triggered On | Status |
   |---|---|---|
   | ravi.kumar | Jun 5, 2024, 9:45 AM | Success |
   | aisha.patel | Jun 5, 2024, 9:00 AM | Success |

3. She realizes Ravi also ran tests (and used the same Run Database!) at 9:45 AM, after her restore
4. Ravi's tests created the unexpected data
5. **Fix:** Aisha and Ravi coordinate — they need to either run at different times or use separate Run Databases

---

## 9. CI Pipeline — How Automated Testing Uses This

CI (Continuous Integration) pipelines are automated test runs triggered by code commits. The TCMS Test Environment API allows the CI system to call the same operations the UI does.

### What Happens in a CI Pipeline

```
Developer pushes code to Git
         │
         ▼
CI pipeline starts automatically (Jenkins/GitHub Actions/etc.)
         │
         ▼
Step 1: CI calls "Sync from Control" API
         → Run Database is reset to clean state
         → Duration: ~5 minutes (CI waits)
         │
         ▼
Step 2: CI runs all automated test cases against the clean Run DB
         │
         ▼
Step 3: CI reports results (pass/fail per test case)
         │
         ▼
Step 4: (Optional) CI creates a snapshot named "ci-run-YYYYMMDD-HHmmss"
         for debugging if tests fail
```

### Why QC Should Know About This

1. **CI and manual QC share the same Run Databases** — if CI runs a sync at 10 AM while you're testing, your database gets wiped. **Check the history before assuming something went wrong with your tests.**

2. **CI runs are recorded in history** — if you see `"ci-pipeline"` as the Triggered By, that's an automated run, not a human.

3. **Best practice:** Ask your Admin to give the CI pipeline its own dedicated Run Database, separate from the QC team's manual testing database. That way they never interfere.

---

## 10. Troubleshooting Common Problems

---

### Problem: "Restore" is taking too long (more than 15 minutes)

**Symptoms:** The spinner is still running, no success or error message.

**Possible causes:**
- The database is very large (hundreds of GB)
- The server is under heavy load
- Network issues between TCMS and the database server

**What to do:**
1. Wait up to 30 minutes before assuming something is wrong
2. Check the Reset History — if the operation appears with a failure status, there was an error
3. Contact the Admin or DBA with the error message from the History

---

### Problem: After restore, data still looks wrong

**Symptoms:** You restored a snapshot but still see unexpected data.

**Possible causes:**
- You accidentally restored the wrong snapshot (check the snapshot name carefully)
- Another user or CI pipeline ran an operation AFTER your restore
- The snapshot was taken when the data was already in a bad state

**What to do:**
1. Check the Reset History — who ran what, and when?
2. Check the snapshot list — are there multiple snapshots with similar names?
3. Restore a different, older snapshot to see if that one is clean

---

### Problem: "Get Connection" shows an error instead of credentials

**Symptoms:** Clicking the key (🔑) icon shows a message like "Connection not configured" instead of the credentials dialog.

**Possible causes:**
- The database registration is incomplete (username/password not saved correctly)
- The server IP or database name in the registration is wrong

**What to do:**
1. Contact the Admin — the environment registration needs to be corrected
2. The Admin will deregister and re-register the environment with the correct details

---

### Problem: "Clone from Control" failed

**Symptoms:** Error notification: *"Clone failed. Check server logs."*

**Possible causes:**
- The Control Database is currently being used by someone (locked)
- Not enough disk space on the server for a new database copy
- The target Run Database name is already in use by another database

**What to do:**
1. Note the exact time of the failure
2. Ask the Admin to check the Reset History for the error message (it's recorded there)
3. The Admin investigates and retries when the issue is resolved

---

### Problem: "Sync from Control" wiped data I needed

**Symptoms:** You ran Sync from Control and lost test data you needed.

**What to do:**
- Unfortunately, there is no "undo" for a sync operation
- For the future: **always take a snapshot before running Sync** if you might need the current data later

This is why the system asks for confirmation before any destructive operation.

---

### Problem: Snapshot creation failed

**Symptoms:** Error notification: *"Snapshot creation failed."*

**Possible causes:**
- Another snapshot with the same name already exists
- The database server doesn't support snapshot functionality (some configurations)
- Disk space on the server is full

**What to do:**
1. Try a different snapshot name (add a timestamp: `"baseline-june05-1430"`)
2. If it still fails, contact the Admin

---

### Problem: The environment table shows no data

**Symptoms:** The Test Environments table is completely empty even though environments should exist.

**Possible causes:**
- You are not logged in (session expired) — refresh the page and log in again
- The TCMS backend service is down — contact the Admin

---

## 11. Quick Reference Card

Print or bookmark this section for fast day-to-day reference.

---

### Icons and What They Do

| Icon | Name | What It Does |
|------|------|--------------|
| 🔑 Key | Get Connection | Shows secure database connection credentials |
| 🔄 Sync | Sync from Control | Replaces Run DB with Control DB (destructive!) |
| 🕐 History | Reset History | Opens audit log of all reset operations |
| 📷 Camera | Snapshots | Manage snapshots for this environment |
| 🗑️ Trash | Deregister | Removes this environment from TCMS |

---

### Snapshot Quick Actions

| Action | Steps |
|--------|-------|
| **Take a snapshot** | Camera icon → type label → "Create Snapshot" button |
| **Restore a snapshot** | Camera icon → find snapshot → Restore icon → Confirm |
| **Delete a snapshot** | Camera icon → find snapshot → Delete icon → Confirm |

---

### Admin Operations Summary

| Operation | Duration | Destructive? | Use When |
|-----------|----------|--------------|----------|
| Register Test DB | Instant | No | Setting up a new environment |
| Clone from Control | 5–30 min | Yes (creates new DB) | First-time setup or full refresh |
| Sync from Control | 5–20 min | Yes (wipes Run DB) | Control DB was updated |
| Create Snapshot | Seconds–1 min | No | Bookmarking a known state |
| Restore Snapshot | 1–5 min | Yes (wipes Run DB back to snapshot) | Before test run; after test run |
| Delete Snapshot | Instant | Yes (snapshot gone) | Cleanup |
| Deregister | Instant | No (just removes TCMS entry) | Environment no longer needed |

---

### The Golden Rules for QC

> 1. **Always restore a snapshot before starting a new test run.** Never assume the database is clean.
>
> 2. **Take a snapshot before any destructive test** (deletes, overrides, month-end close, etc.).
>
> 3. **Check the Reset History if something looks wrong.** Someone else may have changed the database.
>
> 4. **Never test against the Control Database.** It's the source of truth — hands off.
>
> 5. **Communicate with your team.** If multiple people share a Run Database, coordinate who is running what and when.
>
> 6. **Name your snapshots descriptively.** `"before-approval-test-tc089"` is infinitely better than `"snap1"`.

---

### Contacts

| Need | Contact |
|------|---------|
| New environment setup | Admin / DBA |
| Control DB data updates | DBA |
| CI pipeline environment | DevOps |
| TCMS application issues | TCMS System Administrator |
| Test case questions | QC Lead |

---

*Document maintained by: TCMS Administration Team*
*Last updated: 2026-05-29*