Docker Compose

This page documents how to add Lumiere to a plugin (particularly payment gateways) to run the shared tests using the Docker Compose environment.

1. Add Lumiere repository to composer:

   {
     "type": "vcs",
     "url": "[email protected]:skyverge/lumiere.git"
   }
   

2. Require skyverge/lumiere as a development dependency:

   composer require codeception/module-db codeception/module-webdriver lucatume/wp-browser:2.4.8 skyverge/lumiere --update-with-all-dependencies --dev 
   

   Prepend COMPOSER_MEMORY_LIMIT=-1 to the command above if you get a memory related Fatal error.

3. vendor/bin/lumiere up

4. vendor/bin/codecept build

5. Create docker-compose.yml

version: '2'

services:
  codeception:
    volumes:
      - $PWD:/project
      - $PWD:/wordpress/wp-content/plugins/$PLUGIN_DIR

  wordpress:
    volumes:
      - $PWD:/var/www/html/wp-content/plugins/$PLUGIN_DIR

1. Create wp-bootstrap.sh

wp wc payment_gateway update {gateway_id} --enabled=true --user=admin

wp option patch insert woocommerce_{gateway_id}_settings debug_mode "log"
wp option patch insert woocommerce_{gateway_id}_settings transaction_type "authorization"
wp option patch insert woocommerce_{gateway_id}_settings charge_virtual_orders "yes"
wp option patch insert woocommerce_{gateway_id}_settings enable_paid_capture "yes"
wp option patch insert woocommerce_{gateway_id}_settings tokenization "yes"
wp option patch insert woocommerce_{gateway_id}_settings environment "test"

# set gateway specific configuration options

1. Add gateway specific environment variables to .env.lumiere

2. Copy your .env.lumiere to a .env.lumiere.example file that includes any extra environment variables required for that plugin, and delete any sensitive values from it (but keep the keys)

3. Create _support/Traits/PaymentGatewayMethods.php example

4. Copy bootstrap.php and codeception.dist.yml

5. The main extension points are the abstract methods (get_gateway , get_plugin ), place_order , get_credit_cards_data , get_payment_tokens_data.

6. Extend shared Cests

Traits

The shared tests define abstract methods that plugins should implement in order to provide plugin-specific information to the test. One way to avoid having to implement those methods in every Cest, is to create a trait with the necessary methods.

Use the template below to create a tests/_support/Traits/PaymentGatewayMethods.php trait with the get_plugin() and get_gateway() methods, necessary to run shared payment gateway tests.

<?php

namespace SkyVerge\WooCommerce\{PaymentGateway}\Tests\Traits;

trait PaymentGatewayMethods {


	/**
	 * Gets the plugin instance.
	 * 
	 * TODO: define the @return tag
	 */
	protected function get_plugin() {

		// TODO: return an instance of the plugin
	}


	/**
	 * Gets the payment gateway instance.
	 *
	 * TODO: define the @return tag
	 */
	protected function get_gateway() {

		// TODO: return an instance of the payment gateway
	}


}

The next step is to allow that trait to be autoloaded using Codeception's Autoload utility class.

Update codeception.dist.yml to define a bootstrap file by adding the following line after extends:

bootstrap: bootstrap.php

Then, create the tests/bootstrap.php file and declare the trait's namespace:

<?php

use Codeception\Util\Autoload;

// TODO: update namespace
Autoload::addNamespace( 'SkyVerge\WooCommerce\{PaymentGateway}\Tests\Traits', __DIR__ . '/_support/Traits/' );

Frontend

Credit Card Tokenization Tests

Lumiere includes tests for several tokenization scenarios:

To implement those tests in a payment gateway, you should add a tests/frontend/CreditCardTokenizationCest.php class that extends Lumiere's class with the same name:

<?php

use SkyVerge\Lumiere\Tests as Tests;
use SkyVerge\WooCommerce\{PaymentGateway}\Tests\Traits\PaymentGatewayMethods;

class CreditCardTokenizationCest extends Tests\Frontend\PaymentGateways\CreditCardTokenizationCest {


	use PaymentGatewayMethods;


}

1. Remove existing services: docker-compose -f vendor/skyverge/lumiere/docker/docker-compose.yml -f docker-compose.yml --env-file=.env.lumiere.dist --project-name=lumiere down --volumes

2. Build services in case there are changes in the Dockerfile or entry-point scripts docker-compose -f vendor/skyverge/lumiere/docker/docker-compose.yml -f docker-compose.yml --env-file=.env.lumiere.dist --project-name=lumiere build

3. Bootstrap a new Codeception service: docker-compose -f vendor/skyverge/lumiere/docker/docker-compose.yml -f docker-compose.yml --env-file=.env.lumiere.dist --project-name=lumiere run --rm codeception bootstrap

4. Run the frontend test suite docker-compose -f vendor/skyverge/lumiere/docker/docker-compose.yml -f docker-compose.yml --env-file=.env.lumiere.dist --project-name=lumiere run --workdir /wordpress/wp-content/plugins/woocommerce-gateway-{gateway} --rm codeception vendor/bin/codecept run frontend

Ngrok

To use the ngrok service:

1. Get the ngrok auth token from ~/.ngrok2/ngrok.yml or Step 2 in https://dashboard.ngrok.com/get-started/setup
2. Add NGROK_TOKEN= to .env.lumiere
3. Add NGROK_SUBDOMAIN=lumiere to .env.lumiere
4. Update WP_URL and WP_DOMAIN to use lumiere.ngrok.io
5. Reset and bootstrap the Docker environment

If you want to change the subdomain after all the services are up, you can update the .env.lumiere file and run the following commands before trying to run tests again:

docker-compose -f vendor/skyverge/lumiere/docker/docker-compose.yml -f docker-compose.yml --env-file=.env.lumiere.dist --project-name=lumiere up --build --detach ngrok
docker-compose -f vendor/skyverge/lumiere/docker/docker-compose.yml -f docker-compose.yml --env-file=.env.lumiere.dist --project-name=lumiere up --build --detach codeception