diff --git a/astro.config.mjs b/astro.config.mjs index e147abf1..c8e9dc8f 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -86,6 +86,8 @@ export default defineConfig({ label: 'Tutorials', items: [ { label: 'Overview', link: '/tutorials'}, + { label: 'Manual testing – Classic', link: '/tutorials/manual-testing-classic'}, + { label: 'Manual testing – BDD', link: '/tutorials/manual-testing-bdd'}, { label: 'Playwright', link: '/tutorials/playwright'}, { label: 'WebdriverIO', link: '/tutorials/webdriver'}, ], diff --git a/src/content/docs/tutorials/att11_6310.png b/src/content/docs/tutorials/att11_6310.png new file mode 100644 index 00000000..9a524a78 Binary files /dev/null and b/src/content/docs/tutorials/att11_6310.png differ diff --git a/src/content/docs/tutorials/att12_6310.png b/src/content/docs/tutorials/att12_6310.png new file mode 100644 index 00000000..7e31b0de Binary files /dev/null and b/src/content/docs/tutorials/att12_6310.png differ diff --git a/src/content/docs/tutorials/att13_6310.png b/src/content/docs/tutorials/att13_6310.png new file mode 100644 index 00000000..dcbc2b25 Binary files /dev/null and b/src/content/docs/tutorials/att13_6310.png differ diff --git a/src/content/docs/tutorials/att14_6310.png b/src/content/docs/tutorials/att14_6310.png new file mode 100644 index 00000000..7fb16277 Binary files /dev/null and b/src/content/docs/tutorials/att14_6310.png differ diff --git a/src/content/docs/tutorials/att15_6310.png b/src/content/docs/tutorials/att15_6310.png new file mode 100644 index 00000000..a5d3f9cf Binary files /dev/null and b/src/content/docs/tutorials/att15_6310.png differ diff --git a/src/content/docs/tutorials/att16_6310.png b/src/content/docs/tutorials/att16_6310.png new file mode 100644 index 00000000..13bd5480 Binary files /dev/null and b/src/content/docs/tutorials/att16_6310.png differ diff --git a/src/content/docs/tutorials/att17_6310.png b/src/content/docs/tutorials/att17_6310.png new file mode 100644 index 00000000..4eee6ceb Binary files /dev/null and b/src/content/docs/tutorials/att17_6310.png differ diff --git a/src/content/docs/tutorials/att18_6310.png b/src/content/docs/tutorials/att18_6310.png new file mode 100644 index 00000000..55cd9ba5 Binary files /dev/null and b/src/content/docs/tutorials/att18_6310.png differ diff --git a/src/content/docs/tutorials/att1_6310.png b/src/content/docs/tutorials/att1_6310.png new file mode 100644 index 00000000..3a089a5c Binary files /dev/null and b/src/content/docs/tutorials/att1_6310.png differ diff --git a/src/content/docs/tutorials/att2_6310.png b/src/content/docs/tutorials/att2_6310.png new file mode 100644 index 00000000..34bcaed0 Binary files /dev/null and b/src/content/docs/tutorials/att2_6310.png differ diff --git a/src/content/docs/tutorials/att3_6310.png b/src/content/docs/tutorials/att3_6310.png new file mode 100644 index 00000000..0799b4c8 Binary files /dev/null and b/src/content/docs/tutorials/att3_6310.png differ diff --git a/src/content/docs/tutorials/att4_6310.png b/src/content/docs/tutorials/att4_6310.png new file mode 100644 index 00000000..b89e0ce1 Binary files /dev/null and b/src/content/docs/tutorials/att4_6310.png differ diff --git a/src/content/docs/tutorials/att5_6310.png b/src/content/docs/tutorials/att5_6310.png new file mode 100644 index 00000000..e16d258b Binary files /dev/null and b/src/content/docs/tutorials/att5_6310.png differ diff --git a/src/content/docs/tutorials/att6_6310.png b/src/content/docs/tutorials/att6_6310.png new file mode 100644 index 00000000..e358b90d Binary files /dev/null and b/src/content/docs/tutorials/att6_6310.png differ diff --git a/src/content/docs/tutorials/att7_6310.png b/src/content/docs/tutorials/att7_6310.png new file mode 100644 index 00000000..0e168a17 Binary files /dev/null and b/src/content/docs/tutorials/att7_6310.png differ diff --git a/src/content/docs/tutorials/att8_6310.png b/src/content/docs/tutorials/att8_6310.png new file mode 100644 index 00000000..34d77688 Binary files /dev/null and b/src/content/docs/tutorials/att8_6310.png differ diff --git a/src/content/docs/tutorials/att9_6310.png b/src/content/docs/tutorials/att9_6310.png new file mode 100644 index 00000000..58432bc8 Binary files /dev/null and b/src/content/docs/tutorials/att9_6310.png differ diff --git a/src/content/docs/tutorials/images/att10_6310.1.png b/src/content/docs/tutorials/images/att10_6310.1.png new file mode 100644 index 00000000..3467c947 Binary files /dev/null and b/src/content/docs/tutorials/images/att10_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att11_6310.1.png b/src/content/docs/tutorials/images/att11_6310.1.png new file mode 100644 index 00000000..0f264cb3 Binary files /dev/null and b/src/content/docs/tutorials/images/att11_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att12_6310.1.png b/src/content/docs/tutorials/images/att12_6310.1.png new file mode 100644 index 00000000..4748e4e4 Binary files /dev/null and b/src/content/docs/tutorials/images/att12_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att13_6310.1.png b/src/content/docs/tutorials/images/att13_6310.1.png new file mode 100644 index 00000000..6bbd30c1 Binary files /dev/null and b/src/content/docs/tutorials/images/att13_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att14_6310.1.png b/src/content/docs/tutorials/images/att14_6310.1.png new file mode 100644 index 00000000..341e1fc3 Binary files /dev/null and b/src/content/docs/tutorials/images/att14_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att15_6310.1.png b/src/content/docs/tutorials/images/att15_6310.1.png new file mode 100644 index 00000000..1acf73f2 Binary files /dev/null and b/src/content/docs/tutorials/images/att15_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att16_6310.1.png b/src/content/docs/tutorials/images/att16_6310.1.png new file mode 100644 index 00000000..cff41a63 Binary files /dev/null and b/src/content/docs/tutorials/images/att16_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att17_6310.1.png b/src/content/docs/tutorials/images/att17_6310.1.png new file mode 100644 index 00000000..81636b0f Binary files /dev/null and b/src/content/docs/tutorials/images/att17_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att1_6310.1.png b/src/content/docs/tutorials/images/att1_6310.1.png new file mode 100644 index 00000000..7adb9cbb Binary files /dev/null and b/src/content/docs/tutorials/images/att1_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att2_6310.1.png b/src/content/docs/tutorials/images/att2_6310.1.png new file mode 100644 index 00000000..0ff0eef2 Binary files /dev/null and b/src/content/docs/tutorials/images/att2_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att3_6310.1.png b/src/content/docs/tutorials/images/att3_6310.1.png new file mode 100644 index 00000000..1ff9c9e9 Binary files /dev/null and b/src/content/docs/tutorials/images/att3_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att4_6310.1.png b/src/content/docs/tutorials/images/att4_6310.1.png new file mode 100644 index 00000000..b5b46350 Binary files /dev/null and b/src/content/docs/tutorials/images/att4_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att5_6310.1.png b/src/content/docs/tutorials/images/att5_6310.1.png new file mode 100644 index 00000000..7c8e3d8f Binary files /dev/null and b/src/content/docs/tutorials/images/att5_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att6_6310.1.png b/src/content/docs/tutorials/images/att6_6310.1.png new file mode 100644 index 00000000..43c2338b Binary files /dev/null and b/src/content/docs/tutorials/images/att6_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att7_6310.1.png b/src/content/docs/tutorials/images/att7_6310.1.png new file mode 100644 index 00000000..6fd73358 Binary files /dev/null and b/src/content/docs/tutorials/images/att7_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att8_6310.1.png b/src/content/docs/tutorials/images/att8_6310.1.png new file mode 100644 index 00000000..32d5885c Binary files /dev/null and b/src/content/docs/tutorials/images/att8_6310.1.png differ diff --git a/src/content/docs/tutorials/images/att9_6310.1.png b/src/content/docs/tutorials/images/att9_6310.1.png new file mode 100644 index 00000000..8f4a303f Binary files /dev/null and b/src/content/docs/tutorials/images/att9_6310.1.png differ diff --git a/src/content/docs/tutorials/images/manual-testing-bdd-workflow.png b/src/content/docs/tutorials/images/manual-testing-bdd-workflow.png new file mode 100644 index 00000000..eec13867 Binary files /dev/null and b/src/content/docs/tutorials/images/manual-testing-bdd-workflow.png differ diff --git a/src/content/docs/tutorials/images/manual-testing-classic-workflow.png b/src/content/docs/tutorials/images/manual-testing-classic-workflow.png new file mode 100644 index 00000000..35270615 Binary files /dev/null and b/src/content/docs/tutorials/images/manual-testing-classic-workflow.png differ diff --git a/src/content/docs/tutorials/manual-testing-bdd.md b/src/content/docs/tutorials/manual-testing-bdd.md new file mode 100644 index 00000000..b196ee36 --- /dev/null +++ b/src/content/docs/tutorials/manual-testing-bdd.md @@ -0,0 +1,353 @@ +--- +title: Manual Testing – BDD +description: Learn how to create and execute manual tests in Testomat.io using the BDD approach. This tutorial covers project setup, writing Gherkin scenarios, using shared steps, manual test runs, and reporting results. +type: article +url: https://docs.testomat.io/tutorials/manual-testing-bdd +head: + - tag: meta + attrs: + name: keywords + content: BDD, Gherkin, manual testing, scenario, Given When Then, shared steps, test run, Testomat.io +--- + +The **BDD** approach uses Gherkin syntax (`Given / When / Then`) to describe test scenarios as human-readable stories. It suits teams that follow behaviour-driven development or want to share scenarios between manual and automated tests. + +The **Classic** approach stores test descriptions in freeform Markdown — better suited for teams that prefer flexible, plain-language test cases. See [Manual Testing – Classic](./manual-testing-classic.md). + +This tutorial covers the **BDD approach**: from creating a project to finishing a manual run. + +![Testomat.io - Manual testing BDD workflow](./images/manual-testing-bdd-workflow.png) + +## How to Create a Project + +:::note + +Before creating a project, make sure you have a company set up. See [How to Create a Company](https://docs.testomat.io/management/company/administration/#how-to-create-a-company). + +::: + +1. Open the New Project form using one of the following options: +- Click the **+** icon in the top-right corner +- Click the **Create** button on the dashboard +- Click **Create project** if you have no projects yet + + +![Create a project butto ](./att1_6310.png) + +2. Select **BDD**. +3. Enter a name in the **Project Title** field. + +(Optional) Enable **Fill demo data** to pre-populate the project with sample scenarios. + +4. Click **Create**. + +![Create BDD project](./images/att1_6310.1.png) + +:::note + +Before adding scenarios, check a few settings in **Project → Settings**: + +- **Purge Old Runs** — runs are automatically and permanently deleted after 90 days by default (max 365 days). Deleted runs cannot be restored. Update this value before you start executing tests; see [Project Settings](https://docs.testomat.io/management/project/settings/#purge-old-runs) +- **Timezone** — by default, all actions display in UTC+00:00. Set your project timezone so timestamps align with your team's location; see [Project Timezone](https://docs.testomat.io/management/project/settings/#project-timezone). For Created/Executed timestamps in runs, set your personal timezone in **User Account** + +::: + +## How to Set Up Folders and Suites + +In the BDD approach, suites map to **feature files**. Each suite holds one feature and its scenarios. + +:::note + +Start with a folder to keep your project organised from the beginning: **Folder → Suite (Feature) → Scenarios**. You can create suites at the root level too, but folders help you scale later. + +::: +``` +Project +└── Folder + └── Folder + └── Suite = Feature + └── Scenario = Test Case +└── Suite = Feature + └── Scenario = Test Case +``` + +On the Tests page, enter a name in the input field, then click: + +- **+ Suite** — to create a suite (feature file) at the root level +- **Folder** — to create a folder at the root level + +![Default Folder or Suite creation](./images/att2_6310.1.png) + +The folder or suite appears in the test tree. Use the **New folder** and **New suite** links to continue building your structure: + +- Next to a folder or suite — to create nested items inside it +- At the root level — to add more folders or suites at the top level + +You can also click the **+ Test** button in the top-right corner and select: + +- **Folder** — to create a folder +- **Suite** — to create a suite + +![Tests page with folder structure](./images/att3_6310.1.png) + +Once your structure is in place, open a suite to start adding scenarios. + +## How to Write Scenarios + +In the BDD approach, each suite has a **Feature File** editor and individual **Scenario** editors. + +Open a suite and click **Edit Feature File** to write `Scenario:` blocks — each one automatically becomes a separate test case in the suite when saved. It also holds the `Feature:` declaration. Each scenario uses Gherkin keywords: + +```gherkin +Scenario: Successful checkout + Given the user has added an item to the cart + When they proceed to checkout + Then they receive a confirmation email +``` + +![edit the feature file](./images/att4_6310.1.png) + +![Add test case](./images/att5_6310.1.png) + +Set the scenario **priority** (Low, Normal, High, Important, Critical) using the dropdown in the top-left corner of the scenario editor. + +Add tags directly in the scenario using `@`, for example `@smoke` or `@regression`. Tags let you filter scenarios in test plans and runs. + +![Tags & priority](./images/att6_6310.1.png) + +:::note + +If the editor prevents saving due to syntax errors, use **Save to Draft and View Test** to preserve your changes. The next time you open the scenario in edit mode, you can apply or discard the draft. + +::: + +### How to Use Scenario Outline + +Use `Scenario Outline:` when you need to run the same scenario with different data sets — for example, testing multiple user roles, input combinations, or edge cases. This avoids duplicating scenarios that differ only in values. + +A basic scenario hardcodes the values: + +```gherkin +Scenario: Login with valid credentials + Given the user is on the login page + When they enter username "user1" and password "pass123" + Then they are redirected to the dashboard +``` + +A `Scenario Outline:` replaces fixed values with placeholders and provides test data in an `Examples:` table: + +```gherkin +Scenario Outline: Login with different credentials + Given the user is on the login page + When they enter username "" and password "" + Then they should see "" + + Examples: + | username | password | result | + | user1 | pass123 | dashboard | + | user1 | wrongpwd | error message | +``` + +Each row in the `Examples:` table runs as a separate test case during a manual run. + +![Examples](./images/att7_6310.1.png) + +:::note + +Keyword names are case-sensitive — `Scenario Outline` is valid, `scenario outline` is not. You can mix regular `Scenario:` and `Scenario Outline:` blocks in the same feature file. + +::: + +### How to Organise Scenarios + +There are two ways to structure your BDD tests — choose based on your team's workflow: + +- **One feature file, multiple scenarios** — use **Edit Feature File** inside the suite and add all `Scenario:` blocks under a single `Feature:`. Each scenario becomes a test case on save. Best for keeping related scenarios together and editing them as a single file. + +- **One scenario per test case** — create separate BDD test cases individually using **+ Test**. Each test case holds one `Scenario:` block. Best when you need individual tagging, descriptions, or granular control per scenario. + +### Writing Effective Gherkin + +Good Gherkin is readable, reusable, and resilient to UI changes. Three principles that help: + +**Keep steps atomic** — one step, one action. Combining multiple actions into a single step makes it hard to reuse and debug. + +```gherkin +# avoid +When the user selects a product and adds it to the cart + +# better +When the user selects a product +And adds it to the cart +``` + +**Write for intent, not implementation** — describe what the user is trying to do, not how the UI is built. If a button moves or gets renamed, your scenario should still make sense. + +```gherkin +# avoid +When the user clicks the green "Place Order" button in the bottom-right corner + +# better +When the user places the order +``` + +**Always define the starting state** — `Given` sets the exact context before the action. Never assume the system is already in the right state. + +```gherkin +# avoid +When the user proceeds to checkout + +# better +Given the user has items in the cart +When the user proceeds to checkout +``` + +Putting it together — here is how the same test looks in a Classic freeform format versus a well-structured Gherkin scenario: + +Classic test case: +> **Add item and complete purchase** +> 1. Log in to the account +> 2. Search for a product and add it to the cart +> 3. Enter shipping details and confirm payment +> +> **Expected result:** Order confirmation page is displayed with an order number + +Refactored as Gherkin: + +```gherkin +Scenario: Successful purchase with a new shipping address + Given the user is logged in + And the cart contains at least one item + When the user proceeds to checkout + And enters a valid shipping address + And confirms the payment + Then the order confirmation page is displayed + And the order number is visible +``` + +For a full reference of editor features and [Gherkin syntax](https://cucumber.io/docs/gherkin/step-organization#how-cucumber-finds-your-features-and-step-definitions), see [BDD Test Case Editor](https://docs.testomat.io/project/tests/bdd-test-case-editor/). + +## How to Use Shared Steps + +Every time you save a scenario or feature file, Testomat.io automatically adds its steps to the **Steps Database**. No manual setup needed — the database grows as you write. + +To reuse steps from the database while writing: + +1. Start typing a step inside the editor. +2. Enable **Autocomplete Steps** in the editor toolbar — suggestions appear as you type. +3. Select a step from the list to insert it. + +![Shared Steps](./images/att8_6310.1.png) + +:::note + +Do not include `Given`, `When`, or `Then` in the step text itself. Each step is stored without a keyword so it can be used in any context. + +::: + +For more details, see [Steps & Snippets](https://docs.testomat.io/project/steps-snippets/). + +## How to Launch a Manual Run + +Once your scenarios are ready, you can launch a manual run to start executing them. + +**From the Tests page** — the fastest way to start a run without leaving your test tree: + +- **Run a specific suite** — click the extra menu (**...**) next to a suite and select **Run Tests** + +![Run a specific suite](./images/att9_6310.1.png) + +- **Filter and run** — use the filter panel to narrow scenarios by priority, tag, assignee, or other fields, then select the results and click **Run** in the bottom action bar. No test plan needed. + +![Filter and run](./images/att10_6310.1.png) + +**From the Runs page** — use this when you need more control over the run. Click **Manual Run** to open the setup panel. + +The key advantages over launching from the Tests page: + +- **Assign testers** — distribute scenarios across team members; see [How to Assign Users to the Run](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-assign-users-to-the-run) +- **Rungroup and environment** — organise runs and track results by environment; see [How to Run Tests in Rungroups](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-run-tests-in-rungroups) and [How to Select a Test Environment](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-select-a-test-environment) +- **Run as checklist** — hide scenario descriptions for faster execution; see [How to Run Tests as Checklist](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-run-tests-as-checklist) +- **Test scope** — choose what to include: + - **All tests** — all manual tests in the project + - **Test plan** — use a saved plan (see [Plans](https://docs.testomat.io/project/plans/)) + - **Select tests** — pick scenarios manually from the tree, or use filter collections to include/exclude tests by priority, tags, assignees, milestones, labels, and more; see [How to Configure a Manual Run](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-configure-a-manual-run) + - **Without tests** — create the run structure and populate it later +- **Save without launching** — store the run and come back to it later + +![From the Runs page](./images/att11_6310.1.png) + +For the full run setup reference, see [Running Tests Manually](https://docs.testomat.io/project/runs/running-tests-manually/). + +## How to Execute Tests in a Manual Run + +Once the run is launched, select a scenario from the left panel and review its Gherkin steps on the right. + +**Mark the result:** + +- **Passed** — `Cmd+Enter` (Mac) / `Ctrl+Enter` (Windows) +- **Failed** — `Cmd+U` (Mac) / `Ctrl+U` (Windows) +- **Skipped** — `Cmd+I` (Mac) / `Ctrl+I` (Windows) + +**For failed test runs**, add a comment to describe the issue, attach a file as evidence, and use: + +- **Link Defect** — connect an existing bug ticket +- **Edit metafields** — add extra context + +The progress bar at the top tracks Passed, Failed, Skipped, and Pending counts in real time. When all scenarios are done, click **Finish Run**. + +![ Execute Tests in a Manual Run](./images/att12_6310.1.png) + +For checklist mode, step-by-step execution, and time tracking, see [Running Tests Manually](https://docs.testomat.io/project/runs/running-tests-manually/). + +## How to Report a Bug from a Run + +The most common practice is to report a bug right when a test run fails — without leaving the run. When you mark a **test run** as **Failed**, the **Link Defect** action appears. Use it to: + +- **Link an existing issue** — connect the test run to a bug ticket already in your tracker + +![Link an existing issue](./images/att14_6310.1.png) + +- **Create a new issue** — the issue modal opens with the title and description pre-filled from the scenario content (steps, expected results); select the integration, adjust details if needed, and click **Create Issue**. The content is pulled from the test template — see [Templates](https://docs.testomat.io/management/project/templates/#_top) + +![Create a new issue](./images/att13_6310.1.png) + +The linked ticket is attached to the test run and visible in the run and the run report. + +![linked tickets](./images/att15_6310.1.png) + +You can also link or create an issue after the run is finished — in the run report, hover over a failed test run to reveal the **+** and link icons, and use the same options. + +![Link in finished run](./images/att16_6310.1.png) + +:::note + +Bug reporting requires a bug tracker integration to be configured. See [Issues Management Integrations](https://docs.testomat.io/integrations/issues-management/) for supported tools. + +::: + +## How to Export and Share the Run Report + +After completing a run, open the run report and click the **Report** button in the top-right corner. From there you can: + +- **Export as PDF** — download a formatted summary for archiving or sprint reviews. +- **Share report by Email** — enter one or more email addresses; recipients get a link to the extended report view. +- **Download as Spreadsheet** — export results as XLSX for further analysis. +- **Share Report Publicly** — generate a public URL with an optional passcode and expiration date for stakeholders who do not have a Testomat.io account. + +![Export and Share the Run Report](./images/att17_6310.1.png) + +For full details on public sharing settings, see [Run Reports](https://docs.testomat.io/project/runs/reports/#how-to-share-run-report). + +## Go Further + +These features fit into the BDD approach at any stage — use the ones that work for your team: + +- **Templates** — define a default content structure so every new scenario starts with the right format; see [Templates](https://docs.testomat.io/management/project/templates/#_top) +- **Tags & Labels** — organise scenarios with tags and custom fields for flexible filtering and reporting; see [Tags & Labels](https://docs.testomat.io/advanced/tags-labels/) +- **Steps & Snippets** — build a shared steps database to keep Gherkin wording consistent across features; see [Steps & Snippets](https://docs.testomat.io/project/steps-snippets/) +- **Test plans** — save a reusable test scope and launch consistent runs without reselecting scenarios every time; see [Plans](https://docs.testomat.io/project/plans/) +- **Environments** — tag each run with the environment it targets to keep results comparable; see [Environments](https://docs.testomat.io/project/runs/environments/) +- **TQL** — build precise queries to select scenarios by any combination of tags, priority, assignee, status, and more; see [TQL](https://docs.testomat.io/advanced/tql/#_top) +- **Notifications** — set up alerts for run results via Slack, email, or other channels; see [Notifications](https://docs.testomat.io/integrations/report-notifications/) +- **Analytics** — track test coverage, run history, and team progress across the project; see [Analytics](https://docs.testomat.io/project/analytics/) diff --git a/src/content/docs/tutorials/manual-testing-classic.md b/src/content/docs/tutorials/manual-testing-classic.md new file mode 100644 index 00000000..09212caf --- /dev/null +++ b/src/content/docs/tutorials/manual-testing-classic.md @@ -0,0 +1,231 @@ +--- +title: Manual testing – Classic +description: Learn how to create and execute manual tests in Testomat.io using the Classic mode. This tutorial covers project setup, test case creation, manual test runs, test plans, and bug reporting. +type: article +url: https://docs.testomat.io/tutorials/manual-testing-classic +head: + - tag: meta + attrs: + name: keywords + content: manual testing, classic mode, test case, test run, test plan, bug report, Testomat.io +--- + +Testomat.io supports two modes for manual test design: **Classic** and **BDD**. + +**Classic** mode stores test descriptions in Markdown format. It suits teams that write freeform test cases — steps, expected results, preconditions — without a strict Gherkin structure. Use Classic when your tests are written in plain language and you want full flexibility in how you describe them. + +**BDD** mode uses Gherkin syntax (`Given / When / Then`) and is the right choice when your team follows behaviour-driven development or shares scenarios between manual and automated tests. + +This tutorial covers the **Classic workflow**: from creating a project to finishing a run and reporting bugs. + +![Testomat.io - Manual testing Classic workflow](./images/manual-testing-classic-workflow.png) + +## How to Create a Project + +:::note + +Before creating a project, make sure you have a company set up. See [How to Create a Company](https://docs.testomat.io/management/company/administration/#how-to-create-a-company). + +::: + +1. Open the New Project form using one of the following options: +- Click the **+** icon in the top-right corner +- Click the **Create** button on the dashboard +- Click **Create project** if you have no projects yet + +![Create a project butto ](./att1_6310.png) + +2. Select **Classical** mode. +3. Enter a name in the **Project Title** field. + +(Optional) Enable **Fill demo data** to pre-populate the project with sample test cases. + +4. Click **Create**. + +![Create project flow](./att2_6310.png) + +Testomat.io creates the project and opens the Tests page with a README panel on the right. Close the panel to start working. + + +## How to Set Up Folders and Suites + +:::note + +Start with a folder to keep your project organised from the beginning: **Folder → Suite → Test Cases**. You can create suites at the root level too, but folders help you scale later. + +::: +``` +Project +└── Folder + └── Folder + └── Suite + └── Test Case +└── Suite + └── Test Case +``` + +On the Tests page, enter a name in the input field, then click: + +- **+ Suite** — to create a suite at the root level +- **Folder** — to create a folder at the root level + +![Default Folder or Suite creation](./att3_6310.png) + +The folder or suite appears in the test tree. Use the **New folder** and **New suite** links to continue building your structure: + +- Next to a folder or suite — to create nested items inside it +- At the root level — to add more folders or suites at the top level + +You can also click the **+ Test** button in the top-right corner and select: + +- **Folder** — to create a folder +- **Suite** — to create a suite + +![Tests page with folder structure](./att4_6310.png) + +Once your structure is in place, open a suite to start adding test cases. + +## How to Create and Edit Test Cases + +This section covers creating test cases manually. You can also import tests from source code, spreadsheets, or other TMS tools — see [Import](https://docs.testomat.io/project/import-export/import/) for other ways to add tests. + +Open a suite to start adding test cases. There are several ways to work: + +- **New test** in the tree — add a test title directly without opening the suite +- **Add new test** field in the suite sidebar — enter a title and click **Create** +- **Bulk** toggle — paste multiple test titles at once, one per line +- **New Test** button in the top-right — opens the full test editor to fill in all details right away, including priority + + +![Test creation ways](./att5_6310.png) + +:::note + +Priority can only be set when creating a test via the **New Test** button. Tests added through the other methods get **normal** priority by default. + +![Priority](./att6_6310.png) + +::: + +Once a test is created, open it to edit. Add tags in the title using `@` (for example `@smoke`). Write the test content using one of two modes: + +- **Markdown** — write steps, preconditions, and expected results using Markdown syntax directly + +![Markdown format](./att7_6310.png) + +- **Rich editor** — structured editor with dedicated **Step** and **Expected result** fields; use `/` to insert content blocks (steps, snippets, headings) + +![Rich format](./att8_6310.png) + +Both modes work with the same content — switching between Markdown and Rich editor never loses or changes your test. Choose whichever feels more comfortable to write in. Use the **Preview** tab to see how the content will render. + +For a full reference of editor features, see [Test Case Creation and Editing](https://docs.testomat.io/project/tests/test-case-creation-and-editing/). + +## How to Launch a Manual Run + +Once your test cases are ready, you can launch a manual run to start executing them. + +**From the Tests page** — the fastest way to start a run without leaving your test tree: + +- **Run a specific suite** — click the extra menu (**...**) next to a suite and select **Run Tests** + +![Run Tests via Suite](./att9_6310.png) + +- **Filter and run** — use the filter panel to narrow tests by priority, tag, assignee, or other fields, then select the results and click **Run** in the bottom action bar. No test plan needed. + +![Filter and run*](./att11_6310.png) + +**From the Runs page** — use this when you need more control over the run. Click **Manual Run** to open the setup panel. + +The key advantages over launching from the Tests page: + +- **Assign testers** — distribute tests across team members; see [How to Assign Users to the Run](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-assign-users-to-the-run) +- **Rungroup and environment** — organise runs and track results by environment; see [How to Run Tests in Rungroups](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-run-tests-in-rungroups) and [How to Select a Test Environment](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-select-a-test-environment) +- **Run as checklist** — hide test descriptions for faster execution; see [How to Run Tests as Checklist](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-run-tests-as-checklist) +- **Test scope** — choose what to include: + - **All tests** — all manual tests in the project + - **Test plan** — use a saved plan (see [Plans](https://docs.testomat.io/project/plans/)) + - **Select tests** — pick tests manually from the tree, or use filter collections to include/exclude tests by priority, tags, assignees, milestones, labels, and more; see [How to Configure a Manual Run](https://docs.testomat.io/project/runs/running-tests-manually/#how-to-configure-a-manual-run) + - **Without tests** — create the run structure and populate it later +- **Save without launching** — store the run and come back to it later + +![From the Runs page](./att12_6310.png) + +For the full run setup reference, see [Running Tests Manually](https://docs.testomat.io/project/runs/running-tests-manually/). + +## How to Execute Tests in a Manual Run + +Once the run is launched, select a test case from the left panel and review its steps and expected results on the right. + +**Mark the result:** + +- **Passed** — `Cmd+Enter` (Mac) / `Ctrl+Enter` (Windows) +- **Failed** — `Cmd+U` (Mac) / `Ctrl+U` (Windows) +- **Skipped** — `Cmd+I` (Mac) / `Ctrl+I` (Windows) + +**For failed tests**, add a comment to describe the issue, attach a file as evidence, and use: + +- **Link Defect** — connect an existing bug ticket +- **Edit metafields** — add extra context + +The progress bar at the top tracks Passed, Failed, Skipped, and Pending counts in real time. When all tests are done, click **Finish Run**. + +![Manual run view](./att13_6310.png) + +For checklist mode, step-by-step execution, and time tracking, see [Running Tests Manually](https://docs.testomat.io/project/runs/running-tests-manually/). + +## How to Report a Bug from a Run + +The most common practice is to report a bug right when a test run fails — without leaving the run. When you mark a **test run** as **Failed**, the **Link Defect** action appears. Use it to: + +- **Link an existing issue** — connect the test run to a bug ticket already in your tracker + +![Link an existing issue](./att16_6310.png) + +- **Create a new issue** — the issue modal opens with the title and description pre-filled from the test case content (preconditions, steps, expected results); select the integration, adjust details if needed, and click **Create Issue**. The content is pulled from the test template — see [Templates](https://docs.testomat.io/management/project/templates/#_top) + +The linked ticket is attached to the test run and visible in the run and the run report. + +![Create issue modal during run](./att14_6310.png) + +You can also link or create an issue after the run is finished — in the run report, hover over a test run to reveal the **+** and link icons, and use the same options. + +![Run report hover state](./att15_6310.png) + +:::note + +Bug reporting requires a bug tracker integration to be configured. See [Issues Management Integrations](https://docs.testomat.io/integrations/issues-management/) for supported tools. + +::: + +## How to Export and Share the Run Report + +After completing a run, open the run report and click the **Report** button in the top-right corner. + +![Report button](./att18_6310.png) + +From there you can: + +- **Export as PDF** — download a formatted summary for archiving or sprint reviews. +- **Download as spreadsheet** — export results as XLSX for further analysis. +- **Share by email** — enter one or more email addresses; recipients get a link to the extended report view. +- **Share publicly** — generate a public URL with an optional passcode and expiration date for stakeholders who do not have a Testomat.io account. + +![ Export and Share the Run Report](./att17_6310.png) + +For full details on public sharing settings, see [Run Reports](https://docs.testomat.io/project/runs/reports/#how-to-share-run-report). + +## Go Further + +These features fit into the Classic workflow at any stage — use the ones that work for your team: + +- **Templates** — define a default content structure so every new test case starts with the right format; see [Templates](https://docs.testomat.io/management/project/templates/#_top) +- **Tags & Labels** — organise tests with tags and custom fields for flexible filtering and reporting; see [Tags & Labels](https://docs.testomat.io/advanced/tags-labels/) +- **Steps & Snippets** — extract repeated step sequences into reusable blocks so updates apply everywhere at once; see [Steps & Snippets](https://docs.testomat.io/project/steps-snippets/) +- **Test plans** — save a reusable test scope and launch consistent runs without reselecting tests every time; see [Plans](https://docs.testomat.io/project/plans/) +- **Environments** — tag each run with the environment it targets to keep results comparable; see [Environments](https://docs.testomat.io/project/runs/environments/) +- **TQL** — build precise queries to select tests by any combination of tags, priority, assignee, status, and more; see [TQL](https://docs.testomat.io/advanced/tql/#_top) +- **Notifications** — set up alerts for run results via Slack, email, or other channels; see [Notifications](https://docs.testomat.io/integrations/report-notifications/) +- **Analytics** — track test coverage, run history, and team progress across the project; see [Analytics](https://docs.testomat.io/project/analytics/) + +