Tactic Media QA Bundle

https://github.com/tacticmedia/qa-bundle
Admin
Tactic Media QA Bundle captures full-page screenshots during end-to-end testing journeys and...
Tokens:7,365
Snippets:131
Trust Score:4.1
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run Review Host Locally

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docker/review/README.md

Commands to install dependencies and start the application using the built-in PHP server without Docker.

```bash
composer install
php bin/console importmap:install
QA_SCREENSHOTS_DIR=/absolute/path/to/screenshots \
QA_REVIEW_DIR=/absolute/path/to/review \
QA_PROJECT_ROOT=/absolute/path/to/project \
    php -S 127.0.0.1:8000 -t public public/index.php
```

--------------------------------

### Start Review Service with Docker

Source: https://github.com/tacticmedia/qa-bundle/blob/main/demo/README.md

Use this command to build and start the review service container.

```bash
docker compose up --build review
```

--------------------------------

### Start Review Server

Source: https://github.com/tacticmedia/qa-bundle/blob/main/demo/README.md

Starts a local PHP development server to access the screenshot review interface at http://localhost:8000/_dev/screenshots.

```bash
php -S localhost:8000 -t public public/index.php
```

--------------------------------

### Install dependencies

Source: https://github.com/tacticmedia/qa-bundle/blob/main/js/README.md

Install the package and Playwright test runner.

```bash
npm i -D @tacticmedia/qa-capture @playwright/test
```

--------------------------------

### Install QA Bundle dependencies

Source: https://github.com/tacticmedia/qa-bundle/blob/main/README.md

Install the bundle and the optional Panther dependency via Composer.

```bash
composer require --dev tacticmedia/qa-bundle symfony/panther
```

--------------------------------

### Start review service

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/without-php.md

Launch the review container using Docker Compose.

```bash
docker compose up review
```

--------------------------------

### Install dependencies and drivers

Source: https://github.com/tacticmedia/qa-bundle/blob/main/demo/README.md

Run these commands to install PHP dependencies and detect the necessary chromedriver for Panther.

```bash
composer install
vendor/bin/bdi detect drivers
```

--------------------------------

### Run Review Host with Custom Paths

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docker/review/README.md

Command to start the container when screenshot and review directories are located at non-default paths.

```bash
docker run --rm -p 127.0.0.1:8000:8000 \
    -v "$PWD/test-results/screenshots:/data/test-results/screenshots" \
    -v "$PWD/test-results/review:/data/test-results/review" \
    -e QA_SCREENSHOTS_DIR=/data/test-results/screenshots \
    -e QA_REVIEW_DIR=/data/test-results/review \
    ghcr.io/tacticmedia/qa-review:latest
```

--------------------------------

### Run Review Host with Docker

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docker/review/README.md

Standard command to start the review host container with default volume mounts.

```bash
docker run --rm -p 127.0.0.1:8000:8000 \
    -v "$PWD/var/screenshots:/data/var/screenshots" \
    -v "$PWD/var/review:/data/var/review" \
    ghcr.io/tacticmedia/qa-review:latest
```

--------------------------------

### Configure Playwright global setup

Source: https://github.com/tacticmedia/qa-bundle/blob/main/js/README.md

Register the global setup in your Playwright configuration file.

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { createRequire } from 'node:module';

export default defineConfig({
    testDir: './tests',
    globalSetup: createRequire(import.meta.url).resolve('@tacticmedia/qa-capture/playwright/global-setup'),
});
```

--------------------------------

### Build and test JavaScript components

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/development.md

Commands to install dependencies, build assets, and run integration tests for the capture package.

```bash
cd js && npm ci && npm run build && npm test
npx playwright install chromium
QA_SCREENSHOTS_DIR=/tmp/shots npm run test:integration
```

--------------------------------

### Run Playwright Capture Journey

Source: https://github.com/tacticmedia/qa-bundle/blob/main/demo/README.md

Builds the project and executes the Playwright screenshot journey. Requires re-running npm install after rebuilding the JS package.

```bash
cd ../js && npm ci && npm run build
cd ../demo/playwright && npm install && npx playwright install chromium
npm run journey
```

--------------------------------

### Development commands

Source: https://github.com/tacticmedia/qa-bundle/blob/main/js/README.md

Commands for building, testing, and running integration suites.

```bash
npm ci
npm run build
npm test

npx playwright install chromium
QA_SCREENSHOTS_DIR=/tmp/shots npm run test:integration
cd .. && QA_SCREENSHOTS_DIR=/tmp/shots vendor/bin/phpunit --group contract
```

--------------------------------

### Run local development tasks

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/development.md

Standard commands for dependency resolution, static analysis, unit testing, and style checking.

```bash
composer update
vendor/bin/phpstan analyse
vendor/bin/phpunit --exclude-group e2e
composer cs:check
vendor/bin/bdi detect drivers && vendor/bin/phpunit --group e2e
```

--------------------------------

### Run contract tests and build Docker image

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/development.md

Execute contract verification tests and build the local review Docker container.

```bash
QA_SCREENSHOTS_DIR=/tmp/shots vendor/bin/phpunit --group contract
docker build -f docker/review/Dockerfile -t qa-review:local .
```

--------------------------------

### Configure QA bundle directories

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/host-setup.md

Define the storage paths for screenshots and review files in your configuration.

```yaml
when@dev:
    qa:
        screenshots_dir: '%kernel.project_dir%/var/screenshots'
        review_dir: '%kernel.project_dir%/var/review'
```

--------------------------------

### Enable bundle in configuration

Source: https://github.com/tacticmedia/qa-bundle/blob/main/README.md

Register the bundle in config/bundles.php for the dev environment.

```php
TacticMedia\QaBundle\TacticMediaQaBundle::class => ['dev' => true],
```

--------------------------------

### Configure package.json for Webpack Encore

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/host-setup.md

Add the required Stimulus, Turbo, and QA bundle dependencies to your project's package.json.

```json
{
    "devDependencies": {
        "@hotwired/stimulus": "^3.0.0",
        "@hotwired/turbo": "^8.0.0",
        "@tacticmedia/qa-bundle": "file:vendor/tacticmedia/qa-bundle/assets"
    }
}
```

--------------------------------

### Import bundle routes

Source: https://github.com/tacticmedia/qa-bundle/blob/main/README.md

Add the bundle routes to your Symfony configuration under the dev environment.

```yaml
when@dev:
    qa:
        resource: '@TacticMediaQaBundle/config/routes.php'
        type: php
```

--------------------------------

### Configure screenshot options

Source: https://github.com/tacticmedia/qa-bundle/blob/main/js/README.md

Define custom viewports and color schemes in the Playwright configuration.

```typescript
import { defineConfig } from '@playwright/test';
import type { QaScreenshotsOptions } from '@tacticmedia/qa-capture/playwright';

export default defineConfig<{ qaScreenshotsOptions: QaScreenshotsOptions }>({
    use: {
        qaScreenshotsOptions: {
            root: 'var/screenshots',
            viewports: [{ width: 390, height: 844 }, { width: 1920, height: 1080 }],
            colorSchemes: ['light', 'dark'],
        },
    },
});
```

--------------------------------

### Configure Stimulus controllers for QA Bundle

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/host-setup.md

Add this block to assets/controllers.json to enable bundle functionality. Ensure the file exists, as the Flex synchronizer will not create it automatically.

```json
{
    "controllers": {
        "@tacticmedia/qa-bundle": {
            "annotate": { "enabled": true, "fetch": "eager" },
            "clipboard": { "enabled": true, "fetch": "lazy" },
            "confirm": { "enabled": true, "fetch": "lazy" },
            "anchor-highlight": { "enabled": true, "fetch": "lazy" }
        }
    }
}
```

--------------------------------

### Run PHPUnit Capture

Source: https://github.com/tacticmedia/qa-bundle/blob/main/demo/README.md

Executes the PHPUnit test suite to perform full-page screenshot captures.

```bash
vendor/bin/phpunit
```

--------------------------------

### Watch Tailwind Build

Source: https://github.com/tacticmedia/qa-bundle/blob/main/demo/README.md

Run this command to automatically rebuild styles when templates are modified.

```bash
php bin/console tailwind:build --watch
```

--------------------------------

### Review container configuration

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/without-php.md

Define the review service in a Docker Compose file, mapping local screenshot and review directories.

```yaml
# compose.yaml
services:
  review:
    image: ghcr.io/tacticmedia/qa-review:latest
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - ./var/screenshots:/data/var/screenshots
      - ./var/review:/data/var/review
```

--------------------------------

### Capture screenshots in a test

Source: https://github.com/tacticmedia/qa-bundle/blob/main/js/README.md

Use the qaScreenshots fixture to capture screens within a test case.

```typescript
// tests/home.spec.ts
import { test } from '@tacticmedia/qa-capture/playwright';

test('a visitor reads the company site', async ({ page, qaScreenshots }) => {
    await page.goto('https://tacticmedia.com.au/');
    await qaScreenshots.capture('Home');
});
```

--------------------------------

### Configure Tailwind source path

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/host-setup.md

Include the bundle's templates in the Tailwind build process to ensure proper styling of generated markup.

```css
@source "../../vendor/tacticmedia/qa-bundle/templates";
```

--------------------------------

### Screenshot directory tree layout

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/screenshot-sets.md

The required directory structure for storing screenshot PNGs and their corresponding JSON sidecars.

```text
<root>/<mode>/<WxH>/<orientation>/<journey>-<scenario>-<NNN>_<label>.png
                                  ... same basename ................json
```

--------------------------------

### Configure firewall for dev routes

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/host-setup.md

Ensure the firewall permits access to the /_dev/ path required by the review page.

```yaml
security:
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt|dev)|css|images|js)/
            security: false
            stateless: true
```

--------------------------------

### Override layout scripts for Webpack Encore

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/host-setup.md

Replace the default importmap scripts with entry point tags for Webpack Encore.

```twig
{# templates/bundles/TacticMediaQaBundle/layout.html.twig #}
{% extends '@!TacticMediaQa/layout.html.twig' %}

{% block scripts %}
    {{ encore_entry_script_tags('app') }}
{% endblock %}
```

--------------------------------

### Override layout styles

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/host-setup.md

Replace the default CDN-based Tailwind styles with local project assets.

```twig
{% extends '@!TacticMediaQa/layout.html.twig' %}

{% block styles %}
    <link rel="stylesheet" href="{{ asset('styles/app.css') }}">
{% endblock %}
```

--------------------------------

### Implement JourneyScreenshots trait

Source: https://github.com/tacticmedia/qa-bundle/blob/main/README.md

Use the JourneyScreenshots trait in your base test class to enable screenshot capture functionality.

```php
use TacticMedia\QaBundle\Test\JourneyScreenshots;

abstract class JourneyTestCase extends PantherTestCase
{
    use JourneyScreenshots;
}
```

--------------------------------

### Constrain Symfony version for CI reproduction

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/development.md

Use Symfony Flex to lock transitive dependencies to a specific version before running updates.

```bash
composer global require symfony/flex
composer config extra.symfony.require 6.4.*
composer update
```

--------------------------------

### Override screenshot viewports and color schemes

Source: https://github.com/tacticmedia/qa-bundle/blob/main/docs/host-setup.md

Customize the captured viewports and color schemes by overriding these methods in your journey base class.

```php
protected static function screenshotViewports(): array
{
    return [['width' => 1440, 'height' => 900]];
}

protected static function screenshotColorSchemes(): array
{
    return ['light'];
}
```
Tokens:
Raw