https://github.com/LMAX-Exchange/Simple-DSL
Utilities to write a simple DSL in Java
https://github.com/LMAX-Exchange/Simple-DSL
Last synced: about 2 months ago
JSON representation
Utilities to write a simple DSL in Java
- Host: GitHub
- URL: https://github.com/LMAX-Exchange/Simple-DSL
- Owner: LMAX-Exchange
- License: apache-2.0
- Created: 2013-04-16T08:46:00.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2023-07-21T12:55:01.000Z (over 1 year ago)
- Last Synced: 2025-02-19T20:51:45.161Z (about 2 months ago)
- Language: Java
- Size: 485 KB
- Stars: 71
- Watchers: 34
- Forks: 28
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-java - Simple-DSL - DSL是LMAX Exchange使用的一种编写验收测试的风格，旨在平衡人类和机器的可读性。 (测试)
README
Simple-DSL
==========
[](https://github.com/LMAX-Exchange/Simple-DSL/actions?query=workflow%3A%22Java+CI+with+Gradle%22)
[](https://github.com/LMAX-Exchange/Simple-DSL/actions?query=workflow%3ACodeQL)
[](https://github.com/LMAX-Exchange/Simple-DSL/blob/master/LICENCE.txt)
Simple-DSL is a style for writing acceptance tests used at LMAX Exchange that aims to balance human and machine readability. The intention is that developers and non-developers alike can easily read
and understand an acceptance test, and developer IDEs can understand enough of an acceptance test to support useful, but not necessarily comprehensive searching, refactoring and name completion.
The Simple-DSL library provides one component of the DSL for writing acceptance tests - focusing on parsing arguments to methods. The rest of the DSL is heavily
dependent on the system under test but the [wiki](https://github.com/LMAX-Exchange/Simple-DSL/wiki) provides a number of patterns that have proven successful in
building DSLs that stand the test of time.
### Example
A simple test case for placing an order on an exchange might look like:
```java
package com.lmax.exchange.acceptance.test.api;
import com.lmax.exchange.acceptance.dsl.DslTestCase;
import org.junit.Before;
import org.junit.Test;
public class PlaceOrderAcceptanceTest extends DslTestCase
{
@Before
public void setup()
{
adminAPI.createInstrument("name: FTSE100");
registrationAPI.createUser("Bob");
publicAPI.login("Bob");
}
@Test
public void shouldReceiveCancellationMessageAfterCancellingAnOrder()
{
publicAPI.placeOrder("FTSE100", "side: buy", "quantity: 10", "price: 5000", "expectedStatus: UNMATCHED");
}
}
```
The top level variables adminAPI, registrationAPI and publicAPI are provided by the DslTestCase class and represent three key gateways different
types of users use to access the system. This is the type of test that results from applying the various patterns described on the [wiki](https://github.com/LMAX-Exchange/Simple-DSL/wiki). However,
the Simple-DSL library is focused on verifying and parsing the string arguments that are passed to each method. The implementation of publicAPI.placeOrder would look something like:
```java
public void placeOrder(String... args) {
DslParams params = new DslParams(args,
new RequiredParam("instrument"),
new RequiredParam("side").setAllowedValues("buy", "sell"),
new RequiredParam("quantity"),
new OptionalParam("price"),
new OptionalParam("expectedStatus").setAllowedValues("REJECTED", "UNMATCHED", "MATCHED").setDefault("MATCHED"));
long instrumentId = testContext.getInstrumentId(params.value("instrument"));
BigDecimal quantity = params.valueAsBigDecimal("quantity");
boolean buy = params.value("side").equals(buy);
PublicApiDriver driver = getDriver();
String orderId = driver.placeOrder(instrumentId, quantity, buy);
driver.waitForOrderStatus(orderId, params.value("expectedStatus"));
}
```
Creating the DslParams object defines which parameters are accepted by the method, which are required, what values are allowed and any default values. The params object
can then be used to retrieve the values in a variety of forms and uses the driver layer to interact with the system under test to actually place the order. If the steps required to place an order
change in the future, the driver or the way this method uses it can be adapted without needing to change every test that places an order.
### Other Resources
* The [wiki](https://github.com/LMAX-Exchange/Simple-DSL/wiki) provides further examples and patterns to build out a DSL using Simple-DSL.
* The [Testing@LMAX series](https://www.symphonious.net/testing-at-lmax/) provides further detail on the approach we take to testing.